This folder documents the TRR-Backend repository structure and architecture.
Auto-generated by CI (weekly) and make repo-map:
- REPO_STRUCTURE.md - Directory tree listing *
- REPO_STRUCTURE.mermaid.md - Visual structure diagram (Mermaid) * **
- CODE_IMPORT_GRAPH.md - Internal import dependencies (Tree-sitter)
- SCRIPTS_FLOW.md - Script entrypoints and dependencies (Tree-sitter)
* Generated by the Repository Map workflow; may not exist until the first workflow run. ** Complex diagram may not render in GitHub's Mermaid viewer; download the rendered SVG artifact from the workflow run.
Stable template diagrams (auto-generated but manually curated):
- diagrams/git_workflow.md - Git workflow (no prescribed branching/worktree strategy)
- diagrams/system_maps.md - Architecture and data flow diagrams
These diagrams use stable templates and can be manually updated by editing scripts/generate_repo_mermaid.py.
# Generate Tree-sitter-based code diagrams
make repo-map
# Check if diagrams are up to date
make repo-map-checkThe Repository Map workflow runs weekly (Sunday midnight UTC) and on manual trigger:
- Generates repo structure using PGSch/graph-git-repo
- Post-processes REPO_STRUCTURE.mermaid.md to fix Mermaid subgraph/node ID conflicts
- Generates code diagrams using Tree-sitter
- Opens a PR with any changes
Note: The REPO_STRUCTURE.mermaid.md file is post-processed by scripts/fix_repo_structure_mermaid.py to resolve subgraph identifier conflicts that would cause Mermaid rendering errors.
| Type | Location | Updated By |
|---|---|---|
| Generated | generated/ |
CI workflow + make repo-map |
| Hand-authored | diagrams/ |
Manual edits only |
Rule: Never manually edit files in generated/ - they will be overwritten.