How ernestomgz/corvus works
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: core Core · srs_app SRS project · api API · review.py Review svc
Components 21
Ops
Container and bootstrap entrypoints
Django App
Project package and shared application boundary
- manage.py · Primary Django command entrypoint
web/manage.py - SRS project · ASGI/WSGI config, settings, and root URL routing
web/srs_app - Accounts · Custom user model, registration, login, and account URLs
web/accounts - API · Session-authenticated JSON endpoints under /api/v1
web/api
Domain
Core business model and services
- Core · Main bounded context for decks, cards, study sets, and settings
web/core - Review svc · Card selection and review state transitions
web/core/services/review.py - Scheduler · Spaced repetition scheduling and queue logic
web/core/scheduling.py - Decks & cards · Core hierarchy and card management services
web/core/services/decks.py - Study sets · Scope and organize reviewable subsets
web/core/services/study_sets.py - Knowledge maps · Tag-based topic maps layered onto cards
web/core/services/knowledge_maps.py
Ingestion
Import pipelines feeding the core model
- Markdown import · Import ZIP bundles and markdown-based card content
web/import_md - Anki import · Import .apkg packages into normalized core data
web/import_anki
Presentation
Server-rendered UI and assets
- Views · Domain-oriented Django views and HTMX interactions
web/core/views - Templates · Rendered HTML pages and partials for the UI
web/templates - Static assets · Tailwind input and collected CSS/static files
web/static_src
Data
Persistent and file-backed storage
- PostgreSQL · Primary relational store for application state
- Media · Uploaded files and import artifacts on disk
web/media - Migrations · Database schema changes for accounts and core
web/core/migrations
Connections 24
- 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