Repository navigation
DOC: backend directory-structure.md is out of date (35 undocumented files, 2 missing folders, 1 stale entry) #1671
Description
What's wrong with the existing documentation
Problem
docs/backend/backend_python/directory-structure.md no longer matches the
backend source tree. While reading it to understand the backend through docs, I compared
it against the actual files in backend/app/ (checked on dev at commit
5e30cb2) and found missing entries, two folders that are not mentioned
at all, and one entry for a file that no longer exists.
Missing from the document
| Folder | Files not documented |
|---|---|
database/ |
connection.py, memories.py, video_frames.py, videos.py |
models/ |
model_registry.py, session_registry.py |
routes/ |
config.py, dependencies.py, share.py, test.py, videos.py |
schemas/ |
memories.py, share.py, videos.py |
utils/ |
albums.py, extract_location_metadata.py, face_quality.py, faceSearch.py, hardware_detect.py, memory_curator.py, memory_scoring.py, model_bootstrap.py, model_downloader.py, network.py, semantic_labels.py, share.py, takeout_sidecar.py, video_capture_date.py, videos.py |
logging/ (whole folder) |
setup_logging.py |
share/ (whole folder) |
app.py, media.py, registry.py, routes.py, server.py |
That is 35 Python files across 7 folders. The directory tree at the top of the
document also lists only config, database, models, routes, schemas
and utils, so logging/ and share/ are missing there too.
Stale entry
utils/microservice.pyis documented ("Starts sync microservice...") but
the file does not exist in the current tree.
Why this matters
This page is the first place a new backend contributor looks. Right now it
leaves out the album sharing module, memories, videos, model download and
hardware detection, so it is hard to find where those features live.
Proposed fix
Update directory-structure.md so that every file above has an entry with a
short description, written from reading each file, and remove or correct the
stale microservice.py entry. I'd also update the tree at the top to include
logging/ and share/.
Because this is about 35 entries, I can either do it in a single PR or split
it by folder (e.g. one PR for database/ + models/, one for routes/ +
schemas/, one for utils/ + share/ + logging/). Please let me know whichever
you prefer.
I would like to work on this issue. Could this be assigned to me? @rohan-pandeyy
Checks
- I searched existing issues and PRs for this
- I checked the files against the current
devbranch
Add ScreenShots
No response
Record
- I agree to follow this project's Code of Conduct
- I want to work on this issue
Activity
github-actions commentedon Oct 30, 2026
👋 Thanks for opening this issue! The maintainers will review it shortly. Till then, do not open any PR. This is a strict rule we like to follow around here :)
github-actions commentedon Oct 30, 2026
This issue appears semantically similar to the following issues in AOSSIE-Org/PictoPy:
DOC: Remove dead app/schemas/test.py and compress signature-restating docstrings (follow-up to Restructuring comments #1458) (DOC: Remove dead app/schemas/test.py and compress signature-restating docstrings (follow-up to #1458) #1499, open)
DOC: Remove dead app/schemas/test.py and compress signature-restating docstrings (follow-up to #1458) #1499
Similarity: 67.7%
BUG: reset_database.py does not delete the actual application database (BUG: reset_database.py does not delete the actual application database #1375, closed)
BUG: reset_database.py does not delete the actual application database #1375
Similarity: 55.2%
Please review before proceeding.
onitshubham14 commentedon Oct 30, 2026
This is different from #1499: that issue is about in code docstrings and removing
the dead schemas/test.py, while this one is about the prose document
docs/backend/backend_python/directory-structure.md being incomplete with updated repositories.
The only overlap is the test.py files. I'll leave routes/test.py and schemas/test.py
out of the new entries and drop the schemas/test.py entry only after #1499/#1480
land or got closed, and re-check the file list against the latest dev before making a change.