| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # storage |
| 5 | |
| 6 | ## Purpose |
| 7 | Data persistence and file management — SQLite database for download history, file system management for downloaded media, and metadata extraction/storage. |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Exports `Database`, `FileManager`, `MetadataHandler` | |
| 14 | | `database.py` | Async SQLite wrapper — download history, latest aweme timestamps for incremental mode | |
| 15 | | `file_manager.py` | File path construction, directory creation, duplicate detection, file writing | |
| 16 | | `metadata_handler.py` | Extracts and stores metadata (author, description, timestamps) alongside media files | |
| 17 | |
| 18 | ## For AI Agents |
| 19 | |
| 20 | ### Working In This Directory |
| 21 | - `Database` is optional — enabled by `database: true` in config |
| 22 | - `Database.get_latest_aweme_time()` powers the incremental download feature |
| 23 | - `FileManager` handles path construction with author name, aweme ID, and content type |
| 24 | - All file I/O uses `aiofiles` for async operations |
| 25 | |
| 26 | ### Testing Requirements |
| 27 | - Tests: `tests/test_database.py`, `tests/test_file_manager.py` |
| 28 | |
| 29 | ### Common Patterns |
| 30 | - Async context manager for database connections |
| 31 | - `aiosqlite` for non-blocking SQLite access |
| 32 | - File naming: `{author}/{aweme_id}_{type}.{ext}` |
| 33 | |
| 34 | ## Dependencies |
| 35 | |
| 36 | ### Internal |
| 37 | - `utils/helpers.py` — timestamp parsing, size formatting |
| 38 | - `utils/validators.py` — filename sanitization |
| 39 | |
| 40 | ### External |
| 41 | - `aiosqlite` — async SQLite |
| 42 | - `aiofiles` — async file I/O |
| 43 | |
| 44 | <!-- MANUAL: --> |
| 45 |