# ernestomgz/corvus architecture

> Architecture diagram of the GitHub repository ernestomgz/corvus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ernestomgz/corvus
- Repository: https://github.com/ernestomgz/corvus

## Overview

1. **Overall shape**
   Corvus SRS is a single Django 5 monolith split into a few app-level subsystems rather than separate services. The main runtime is the `web` container, backed by PostgreSQL, with Django serving both the HTML UI and the JSON API from the same codebase.

2. **Entry points and deployment**
   The app boots through `web/manage.py` and the Django project package `web/srs_app/`. `docker-compose.yml` defines the local stack, and `web/Dockerfile` builds the web image with the Tailwind asset pipeline baked in. Static files are collected into Django’s static directories, while media uploads live under `web/media`.

3. **Core domain boundary**
   Most business logic lives in `web/core/`. This is the central bounded context for decks, cards, study sets, review state, scheduling, knowledge maps, and user settings. The rest of the repository mostly wraps or feeds this domain: UI views, importers, API endpoints, and management commands.

4. **Data model and persistence**
   The schema evolves through Django migrations in `web/core/migrations` and `web/accounts/migrations`. The core models track the flashcard hierarchy, card types, study sets, review-related state, knowledge map tags, and user preferences. The README’s mention of a custom user model and PBKDF2 hashing is implemented in the `accounts` app and persisted in the same database.

5. **Review engine**
   Spaced repetition behavior is concentrated in `web/core/scheduling.py` and `web/core/services/review.py`. This layer owns SM-2 style transitions, queue selection, learning/relearning handling, leech tagging, and the logic that decides what card comes next. Views in `web/core/views/review.py` and API endpoints both depend on this service layer rather than embedding scheduling rules directly.

6. **Content management UI**
   The HTML interface is organized by domain: decks, cards, card types, study sets, knowledge maps, review, and settings. Each area has its own URLs and views under `web/core/urls/` and `web/core/views/`, with templates under `web/templates/core/...`. HTMX is used for partial updates and inline interactions, especially around deck creation/editing and review actions.

7. **Import pipelines**
   Imports are treated as first-class subsystems, not ad hoc scripts. `web/import_md/` handles Markdown/Logseq-style ZIP bundles, while `web/import_anki/` parses Anki `.apkg` packages. Each importer has its own forms, services, and views, and both feed normalized data into the core deck/card model with idempotent or state-preserving behavior where possible.

8. **Knowledge maps**
   Knowledge maps are a separate feature layered onto the core card model. JSON maps are imported through API or UI flows, then converted into a tag taxonomy like `km:<map-slug>:<node-key>`. The docs and `samples/knowledge_map.json` show that cards can be linked to a structured topic tree for practice and filtering, which gives the system a second organizational dimension beyond decks.

9. **Public API boundary**
   `web/api/` exposes session-authenticated JSON endpoints under `/api/v1`, covering auth, decks, cards, review flow, imports, and knowledge map import. The API is not a separate service; it shares models, services, and authentication with the HTML app, which keeps behavior consistent across UI and programmatic access.

10. **Authentication and accounts**
    `web/accounts/` provides registration, login, and user administration. This app is a thin identity boundary around the custom user model and session auth. Permission-sensitive tests in `web/tests/` suggest the repo is careful about ownership checks across decks, cards, review operations, and import artifacts.

11. **Presentation and assets**
    The frontend is server-rendered Django templates with Tailwind CSS and HTMX, not a client-heavy SPA. CSS sources live in `web/static_src/`, compiled assets in `web/static/`, and template partials support incremental page updates. This keeps the presentation layer tightly coupled to server state and domain services.

12. **Operational and bootstrap concerns**
    `seed_demo` in `web/core/management/commands/` seeds a demo user and sample content for local setup. The repo also includes `samples/` for ready-to-import card bundles and a `web/imports_tmp/` staging area for transient import work. Together these indicate a workflow centered on local self-hosting and repeatable import/re-import scenarios.

13. **Test boundary**
    The pytest suite in `web/tests/` covers the critical architecture seams: scheduler transitions, importer behavior, API flows, permission boundaries, knowledge maps, and end-to-end user flows. That test layout mirrors the app structure closely, which is useful when drawing the architecture diagram because it shows which modules are intended to stay stable as boundaries.

14. **Diagram takeaway**
    The simplest accurate diagram is: browser/UI and API clients on top; Django project routing into account/core/import/api apps; core services and scheduler as the domain engine; PostgreSQL as the persistent store; media/static files as separate file-boundary concerns; and importers/knowledge-map ingestion as auxiliary ingestion pipelines feeding the same core model.

Main entry points: [`web/core`](https://github.com/ernestomgz/corvus/tree/main/web/core) (Core), [`web/srs_app`](https://github.com/ernestomgz/corvus/tree/main/web/srs_app) (SRS project), [`web/api`](https://github.com/ernestomgz/corvus/tree/main/web/api) (API), [`web/core/services/review.py`](https://github.com/ernestomgz/corvus/blob/main/web/core/services/review.py) (Review svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Ops"]
  node_docker_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_web_container["Web image<br/>container"]
  node_seed_demo["Seed demo<br/>bootstrap command<br/>[seed_demo.py]"]
end

subgraph group_app["Django App"]
  node_manage_py["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_project_pkg["SRS project<br/>django project"]
  node_accounts_app["Accounts<br/>identity app"]
  node_api_app["API"]
end

subgraph group_domain["Domain"]
  node_core_app["Core<br/>domain app"]
  node_review_service["Review svc<br/>[review.py]"]
  node_scheduler["Scheduler<br/>algorithm<br/>[scheduling.py]"]
  node_decks_cards["Decks & cards<br/>model layer<br/>[decks.py]"]
  node_study_sets["Study sets<br/>feature<br/>[study_sets.py]"]
  node_knowledge_maps["Knowledge maps<br/>feature<br/>[knowledge_maps.py]"]
end

subgraph group_ingest["Ingestion"]
  node_import_md["Markdown import<br/>ingestion app"]
  node_import_anki["Anki import<br/>ingestion app"]
end

subgraph group_presentation["Presentation"]
  node_views_templates["Views<br/>html ui"]
  node_templates["Templates"]
  node_static_assets["Static assets<br/>frontend assets"]
end

subgraph group_data["Data"]
  node_postgres[("PostgreSQL<br/>database")]
  node_media["Media<br/>file store"]
  node_migrations["Migrations<br/>schema evolution"]
end

node_docker_compose -->|"builds"| node_web_container
node_web_container -->|"starts"| node_manage_py
node_manage_py -->|"boots"| node_project_pkg
node_project_pkg -->|"routes"| node_accounts_app
node_project_pkg -->|"routes"| node_api_app
node_project_pkg -->|"routes"| node_core_app
node_core_app -->|"drives"| node_views_templates
node_views_templates -->|"renders"| node_templates
node_templates -->|"uses"| node_static_assets
node_core_app -->|"contains"| node_review_service
node_review_service -->|"delegates"| node_scheduler
node_core_app -->|"contains"| node_decks_cards
node_core_app -->|"contains"| node_study_sets
node_core_app -->|"contains"| node_knowledge_maps
node_api_app -->|"reads/writes"| node_core_app
node_api_app -->|"uses"| node_review_service
node_import_md -->|"feeds"| node_core_app
node_import_anki -->|"feeds"| node_core_app
node_core_app -->|"evolves via"| node_migrations
node_accounts_app -->|"evolves via"| node_migrations
node_project_pkg -->|"persists to"| node_postgres
node_project_pkg -->|"stores files"| node_media
node_seed_demo -->|"seeds"| node_core_app
node_seed_demo -->|"writes"| node_postgres

click node_docker_compose "https://github.com/ernestomgz/corvus/blob/main/docker-compose.yml"
click node_web_container "https://github.com/ernestomgz/corvus/tree/main/web/Dockerfile"
click node_manage_py "https://github.com/ernestomgz/corvus/blob/main/web/manage.py"
click node_project_pkg "https://github.com/ernestomgz/corvus/tree/main/web/srs_app"
click node_accounts_app "https://github.com/ernestomgz/corvus/tree/main/web/accounts"
click node_api_app "https://github.com/ernestomgz/corvus/tree/main/web/api"
click node_core_app "https://github.com/ernestomgz/corvus/tree/main/web/core"
click node_review_service "https://github.com/ernestomgz/corvus/blob/main/web/core/services/review.py"
click node_scheduler "https://github.com/ernestomgz/corvus/blob/main/web/core/scheduling.py"
click node_decks_cards "https://github.com/ernestomgz/corvus/blob/main/web/core/services/decks.py"
click node_study_sets "https://github.com/ernestomgz/corvus/blob/main/web/core/services/study_sets.py"
click node_knowledge_maps "https://github.com/ernestomgz/corvus/blob/main/web/core/services/knowledge_maps.py"
click node_import_md "https://github.com/ernestomgz/corvus/tree/main/web/import_md"
click node_import_anki "https://github.com/ernestomgz/corvus/tree/main/web/import_anki"
click node_views_templates "https://github.com/ernestomgz/corvus/tree/main/web/core/views"
click node_templates "https://github.com/ernestomgz/corvus/tree/main/web/templates"
click node_static_assets "https://github.com/ernestomgz/corvus/tree/main/web/static_src"
click node_media "https://github.com/ernestomgz/corvus/tree/main/web/media"
click node_migrations "https://github.com/ernestomgz/corvus/tree/main/web/core/migrations"
click node_seed_demo "https://github.com/ernestomgz/corvus/blob/main/web/core/management/commands/seed_demo.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_docker_compose,node_web_container,node_seed_demo toneBlue
class node_manage_py,node_project_pkg,node_accounts_app,node_api_app toneAmber
class node_core_app,node_review_service,node_scheduler,node_decks_cards,node_study_sets,node_knowledge_maps toneMint
class node_import_md,node_import_anki toneRose
class node_views_templates,node_templates,node_static_assets toneIndigo
class node_postgres,node_media,node_migrations toneTeal
```

## Components

### Ops

Container and bootstrap entrypoints

- [Compose](https://github.com/ernestomgz/corvus/blob/main/docker-compose.yml): deployment · Local stack definition for the monolith and database · `docker-compose.yml`
- [Web image](https://github.com/ernestomgz/corvus/tree/main/web/Dockerfile): container · Django runtime image with asset build support · `web/Dockerfile`
- [Seed demo](https://github.com/ernestomgz/corvus/blob/main/web/core/management/commands/seed_demo.py): bootstrap command · Management command for demo users and sample content · `web/core/management/commands/seed_demo.py`

### Django App

Project package and shared application boundary

- [manage.py](https://github.com/ernestomgz/corvus/blob/main/web/manage.py): entrypoint · Primary Django command entrypoint · `web/manage.py`
- [SRS project](https://github.com/ernestomgz/corvus/tree/main/web/srs_app): django project · ASGI/WSGI config, settings, and root URL routing · `web/srs_app`
- [Accounts](https://github.com/ernestomgz/corvus/tree/main/web/accounts): identity app · Custom user model, registration, login, and account URLs · `web/accounts`
- [API](https://github.com/ernestomgz/corvus/tree/main/web/api): json api · Session-authenticated JSON endpoints under /api/v1 · `web/api`

### Domain

Core business model and services

- [Core](https://github.com/ernestomgz/corvus/tree/main/web/core): domain app · Main bounded context for decks, cards, study sets, and settings · `web/core`
- [Review svc](https://github.com/ernestomgz/corvus/blob/main/web/core/services/review.py): service · Card selection and review state transitions · `web/core/services/review.py`
- [Scheduler](https://github.com/ernestomgz/corvus/blob/main/web/core/scheduling.py): algorithm · Spaced repetition scheduling and queue logic · `web/core/scheduling.py`
- [Decks & cards](https://github.com/ernestomgz/corvus/blob/main/web/core/services/decks.py): model layer · Core hierarchy and card management services · `web/core/services/decks.py`
- [Study sets](https://github.com/ernestomgz/corvus/blob/main/web/core/services/study_sets.py): feature · Scope and organize reviewable subsets · `web/core/services/study_sets.py`
- [Knowledge maps](https://github.com/ernestomgz/corvus/blob/main/web/core/services/knowledge_maps.py): feature · Tag-based topic maps layered onto cards · `web/core/services/knowledge_maps.py`

### Ingestion

Import pipelines feeding the core model

- [Markdown import](https://github.com/ernestomgz/corvus/tree/main/web/import_md): ingestion app · Import ZIP bundles and markdown-based card content · `web/import_md`
- [Anki import](https://github.com/ernestomgz/corvus/tree/main/web/import_anki): ingestion app · Import .apkg packages into normalized core data · `web/import_anki`

### Presentation

Server-rendered UI and assets

- [Views](https://github.com/ernestomgz/corvus/tree/main/web/core/views): html ui · Domain-oriented Django views and HTMX interactions · `web/core/views`
- [Templates](https://github.com/ernestomgz/corvus/tree/main/web/templates): server templates · Rendered HTML pages and partials for the UI · `web/templates`
- [Static assets](https://github.com/ernestomgz/corvus/tree/main/web/static_src): frontend assets · Tailwind input and collected CSS/static files · `web/static_src`

### Data

Persistent and file-backed storage

- **PostgreSQL**: database · Primary relational store for application state
- [Media](https://github.com/ernestomgz/corvus/tree/main/web/media): file store · Uploaded files and import artifacts on disk · `web/media`
- [Migrations](https://github.com/ernestomgz/corvus/tree/main/web/core/migrations): schema evolution · Database schema changes for accounts and core · `web/core/migrations`

## Connections

- Compose → Web image: builds · Compose defines the web runtime
- Web image → manage.py: starts · Container launches Django through the manage entrypoint
- manage.py → SRS project: boots · Entrypoint loads settings and root URLs
- SRS project → Accounts: routes · Project includes account URLs and auth views
- SRS project → API: routes · Project mounts the JSON API boundary
- SRS project → Core: routes · Project mounts the main domain app
- Core → Views: drives · Core domain is exposed through views and UI actions
- Views → Templates: renders · Views render server-side templates and partials
- Templates → Static assets: uses · Templates rely on collected CSS and HTMX-enabled assets
- Core → Review svc: contains · Review orchestration lives in core services
- Review svc → Scheduler: delegates · Review flow depends on scheduling rules
- Core → Decks & cards: contains · Deck and card operations form the main content model
- Core → Study sets: contains · Study scope management sits in the core domain
- Core → Knowledge maps: contains · Knowledge map tags and linking are part of the domain
- API → Core: reads/writes · API shares the same domain models and services
- API → Review svc: uses · Review endpoints reuse the review service layer
- Markdown import → Core: feeds · Markdown imports normalize into decks and cards
- Anki import → Core: feeds · Anki imports normalize into the same core model
- Core → Migrations: evolves via · Core schema is managed through migrations
- Accounts → Migrations: evolves via · User model and auth schema are migrated in-place
- SRS project → PostgreSQL: persists to · All apps share the same database
- SRS project → Media: stores files · Uploaded media and transient artifacts live on disk
- Seed demo → Core: seeds · Bootstrap command creates demo content in the core domain
- Seed demo → PostgreSQL: writes · Seed data is persisted to the database
