# uccser/cs-field-guide architecture

> Architecture diagram of the GitHub repository uccser/cs-field-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uccser/cs-field-guide
- Repository: https://github.com/uccser/cs-field-guide

## Overview

CSFG is a multilingual online computer-science learning guide for students and educators. The main workflow is to browse chapter content and interactive learning materials; supporting branches include appendices, curriculum guides, and search. Content loaders convert localized Markdown and YAML into database-backed models, while interactive references are checked during section loading. The tree and README establish the product scope, and excerpts document only selected loader and search relationships; other application wiring is therefore left unasserted.

Main entry points: [`csfieldguide/search/settings.py`](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/settings.py) (Search sources), [`csfieldguide/utils/TranslatableModelLoader.py`](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/TranslatableModelLoader.py) (Translation loader), [`csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py`](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py) (Chapter sections), [`csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py`](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py) (Guide sections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Learning content"]
  node_chapters[("Chapters<br/>[models.py]")]
  node_chapter_views["Chapter pages<br/>[views.py]"]
  node_appendices[("Appendices<br/>[models.py]")]
  node_appendix_views["Appendix pages<br/>[views.py]"]
  node_guides[("Curriculum guides<br/>[models.py]")]
  node_guide_views["Guide pages<br/>[views.py]"]
  node_chapter_loader["Chapter sections"]
  node_appendix_loader["Appendix loader"]
  node_guide_loader["Guide sections"]
end

subgraph group_interactive["Interactive learning"]
  node_interactive_models[("Interactive catalog<br/>[models.py]")]
  node_interactive_views["Interactive pages<br/>[views.py]"]
  node_interactive_assets["Interactive assets"]
end

subgraph group_search["Search"]
  node_search_config["Search sources<br/>[settings.py]"]
  node_search_index[("Search index<br/>[models.py]")]
  node_index_builder["Index builder"]
  node_search_utils["Search utilities<br/>[utils.py]"]
  node_search_views["Search pages<br/>[views.py]"]
end

subgraph group_platform["Content platform"]
  node_base_loader["Markdown loader<br/>[BaseLoader.py]"]
  node_translation_loader["Translation loader"]
  node_file_checks["Content checks"]
  node_settings["Site settings<br/>[base.py]"]
  node_routing["Site routing<br/>[urls.py]"]
  node_site_views["Site views<br/>[views.py]"]
end

node_learner(("Learner"))

node_learner -.->|"browses"| node_chapter_views
node_learner -.->|"browses"| node_appendix_views
node_learner -.->|"browses"| node_guide_views
node_learner -.->|"searches"| node_search_views
node_chapter_loader -->|"inherits from"| node_translation_loader
node_chapter_loader -->|"updates sections"| node_chapters
node_chapter_loader -->|"checks interactives"| node_file_checks
node_appendix_loader -->|"inherits from"| node_translation_loader
node_appendix_loader -->|"updates pages"| node_appendices
node_guide_loader -->|"inherits from"| node_translation_loader
node_guide_loader -->|"updates sections"| node_guides
node_guide_loader -->|"checks interactives"| node_file_checks
node_translation_loader -->|"inherits from"| node_base_loader
node_chapter_views -.->|"reads"| node_chapters
node_appendix_views -.->|"reads"| node_appendices
node_guide_views -.->|"reads"| node_guides
node_interactive_views -.->|"reads"| node_interactive_models
node_interactive_models -.->|"references"| node_interactive_assets
node_search_config -->|"indexes"| node_chapters
node_search_config -->|"indexes"| node_appendices
node_search_config -->|"indexes"| node_interactive_models
node_index_builder -->|"loads sources"| node_search_config
node_index_builder -->|"gets model ID"| node_search_utils
node_index_builder -->|"writes entries"| node_search_index
node_search_views -.->|"queries"| node_search_index
node_routing -->|"routes to"| node_site_views
node_settings -.->|"configures"| node_site_views

click node_chapters "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/models.py"
click node_chapter_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/views.py"
click node_appendices "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/models.py"
click node_appendix_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/views.py"
click node_guides "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/models.py"
click node_guide_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/views.py"
click node_chapter_loader "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py"
click node_appendix_loader "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/management/commands/_AppendicesLoader.py"
click node_guide_loader "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py"
click node_interactive_models "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/interactives/models.py"
click node_interactive_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/interactives/views.py"
click node_interactive_assets "https://github.com/uccser/cs-field-guide/tree/develop/csfieldguide/static/interactives"
click node_search_config "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/settings.py"
click node_search_index "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/models.py"
click node_index_builder "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/management/commands/rebuild_search_indexes.py"
click node_search_utils "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/utils.py"
click node_search_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/views.py"
click node_base_loader "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/BaseLoader.py"
click node_translation_loader "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/TranslatableModelLoader.py"
click node_file_checks "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/check_required_files.py"
click node_settings "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/settings/base.py"
click node_routing "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/urls.py"
click node_site_views "https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/views.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chapters,node_chapter_views,node_appendices,node_appendix_views,node_guides,node_guide_views,node_chapter_loader,node_appendix_loader,node_guide_loader toneBlue
class node_interactive_models,node_interactive_views,node_interactive_assets toneAmber
class node_search_config,node_search_index,node_index_builder,node_search_utils,node_search_views toneMint
class node_base_loader,node_translation_loader,node_file_checks,node_settings,node_routing,node_site_views toneRose
class node_learner toneIndigo
```

## Components

### Learning content

- [Chapters](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/models.py): `csfieldguide/chapters/models.py`
- [Chapter pages](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/views.py): `csfieldguide/chapters/views.py`
- [Appendices](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/models.py): `csfieldguide/appendices/models.py`
- [Appendix pages](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/views.py): `csfieldguide/appendices/views.py`
- [Curriculum guides](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/models.py): `csfieldguide/curriculum_guides/models.py`
- [Guide pages](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/views.py): `csfieldguide/curriculum_guides/views.py`
- [Chapter sections](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py): `csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py`
- [Appendix loader](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/appendices/management/commands/_AppendicesLoader.py): `csfieldguide/appendices/management/commands/_AppendicesLoader.py`
- [Guide sections](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py): `csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py`

### Interactive learning

- [Interactive catalog](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/interactives/models.py): `csfieldguide/interactives/models.py`
- [Interactive pages](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/interactives/views.py): `csfieldguide/interactives/views.py`
- [Interactive assets](https://github.com/uccser/cs-field-guide/tree/develop/csfieldguide/static/interactives): `csfieldguide/static/interactives`

### Search

- [Search sources](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/settings.py): `csfieldguide/search/settings.py`
- [Search index](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/models.py): `csfieldguide/search/models.py`
- [Index builder](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/management/commands/rebuild_search_indexes.py): `csfieldguide/search/management/commands/rebuild_search_indexes.py`
- [Search utilities](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/utils.py): `csfieldguide/search/utils.py`
- [Search pages](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/search/views.py): `csfieldguide/search/views.py`

### Content platform

- [Markdown loader](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/BaseLoader.py): `csfieldguide/utils/BaseLoader.py`
- [Translation loader](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/TranslatableModelLoader.py): `csfieldguide/utils/TranslatableModelLoader.py`
- [Content checks](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/utils/check_required_files.py): `csfieldguide/utils/check_required_files.py`
- [Site settings](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/settings/base.py): `csfieldguide/config/settings/base.py`
- [Site routing](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/urls.py): `csfieldguide/config/urls.py`
- [Site views](https://github.com/uccser/cs-field-guide/blob/develop/csfieldguide/config/views.py): `csfieldguide/config/views.py`

### Other components

- **Learner**

## Connections

- Learner → Chapter pages: browses (evidence: `README.md`)
- Learner → Appendix pages: browses (evidence: `README.md`)
- Learner → Guide pages: browses (evidence: `README.md`)
- Learner → Search pages: searches (evidence: `README.md`)
- Chapter sections → Translation loader: inherits from (evidence: `csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py`)
- Chapter sections → Chapters: updates sections (evidence: `csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py`)
- Chapter sections → Content checks: checks interactives (evidence: `csfieldguide/chapters/management/commands/_ChapterSectionsLoader.py`)
- Appendix loader → Translation loader: inherits from (evidence: `csfieldguide/appendices/management/commands/_AppendicesLoader.py`)
- Appendix loader → Appendices: updates pages (evidence: `csfieldguide/appendices/management/commands/_AppendicesLoader.py`)
- Guide sections → Translation loader: inherits from (evidence: `csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py`)
- Guide sections → Curriculum guides: updates sections (evidence: `csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py`)
- Guide sections → Content checks: checks interactives (evidence: `csfieldguide/curriculum_guides/management/commands/_CurriculumGuideSectionsLoader.py`)
- Translation loader → Markdown loader: inherits from (evidence: `csfieldguide/utils/TranslatableModelLoader.py`)
- Chapter pages → Chapters: reads
- Appendix pages → Appendices: reads
- Guide pages → Curriculum guides: reads
- Interactive pages → Interactive catalog: reads
- Interactive catalog → Interactive assets: references
- Search sources → Chapters: indexes (evidence: `csfieldguide/search/settings.py`)
- Search sources → Appendices: indexes (evidence: `csfieldguide/search/settings.py`)
- Search sources → Interactive catalog: indexes (evidence: `csfieldguide/search/settings.py`)
- Index builder → Search sources: loads sources (evidence: `csfieldguide/search/management/commands/rebuild_search_indexes.py`)
- Index builder → Search utilities: gets model ID (evidence: `csfieldguide/search/management/commands/rebuild_search_indexes.py`)
- Index builder → Search index: writes entries (evidence: `csfieldguide/search/management/commands/rebuild_search_indexes.py`)
- Search pages → Search index: queries
- Site routing → Site views: routes to (evidence: `csfieldguide/config/urls.py`)
- Site settings → Site views: configures