Skip to content

Current State

Scope and evidence

This snapshot is based on the current working tree of the backend branch. It uses only repo evidence under:

  • app/
  • db/
  • tests/
  • docs/
  • .github/
  • render.yaml
  • Dockerfile
  • postman/

The scope here is the backend runtime and the backend documentation set. Frontend and admin artifacts are mentioned only when they affect the backend branch or create documentation drift.

What exists today

Runtime and process model

The branch currently runs as a single FastAPI process:

  • app entrypoint: app/main.py
  • router registration: app/api/router.py
  • Docker startup: root Dockerfile
  • deployment definition: render.yaml

The active runtime shape today is:

  • one api Render web service for the backend
  • one docs static site
  • FastAPI BackgroundTasks for ingestion dispatch started from admin routes
  • APScheduler initialized at app startup by app/services/background_jobs.py
  • no separate worker service in render.yaml

Backend capabilities implemented in code

The codebase currently contains:

  • auth and role-aware access control in app/core/auth.py
  • request ID and in-memory rate limiting middleware in app/core/middleware.py
  • chat orchestration in app/agents/teacher_agent.py
  • grounded answer generation in app/services/llm.py
  • hybrid retrieval in app/services/retrieval_pipeline.py
  • scraping support under app/services/scrapers/
  • scrape persistence and handoff support in app/services/scraper_service.py and app/services/ingestion_handoff.py
  • ingestion services in app/services/ingestion.py and app/services/hybrid_ingestion.py
  • wallet reservation and settlement in app/services/wallet_reservation.py
  • quiz generation endpoints in app/api/routers/quiz.py
  • metrics endpoints in app/api/routers/metrics.py

The registered router groups in app/api/router.py are:

  • /auth
  • /me
  • /chat
  • /admin
  • /wallet
  • /scraping
  • /curriculum
  • /metrics
  • /quizzes
  • /health

There is no global /api prefix in the active FastAPI app.

Data and infrastructure assets

The backend currently depends on:

  • Supabase Auth
  • Supabase Postgres
  • Supabase SQL migrations and SQL RPCs
  • Supabase storage bucket setup via SQL migration
  • Pinecone
  • OpenAI
  • Render

The repo contains:

  • baseline schema in db/bootstrap.sql
  • 34 migration files under db/migrations/
  • backend tests under tests/ with 42 tracked test files
  • Postman sync assets under postman/
  • CI workflows under .github/workflows/

Documentation layout present in the working tree

Two documentation layouts currently coexist:

  • older numbered and historical trees such as docs/00_overview/, docs/10_current_state/, docs/20_runbooks/, docs/30_design/, docs/90_ops/, docs/Artifacts/, and docs/Postman/
  • newer active-looking trees such as docs/architecture/, docs/runbooks/, docs/contributing/, docs/implementation/, docs/adr/, and this docs/current-state.md

mkdocs.yml and docs/index.md currently point to the newer layout, while the older layout still exists on disk.

What is authoritative today

The current repo evidence establishes this order of authority:

  1. Implementation code under app/
  2. Effective database state as db/bootstrap.sql plus all files in db/migrations/
  3. Active backend docs under docs/

That order is stated directly in docs/contributing/documentation-policy.md.

Additional authority rules already present in the repo:

  • docs/architecture/integration-surfaces.md says code under app/api/routers/ is canonical when route artifacts drift.
  • docs/architecture/data-model.md says db/bootstrap.sql alone is not sufficient and that the effective schema is baseline plus migrations.
  • docs/index.md says intutype_backend_source_of_truth.md is design input, not automatically published truth.
  • docs/index.md also says docs/90_ops/ and docs/99_archive/ are historical material, not primary navigation.

Practically, today the most reliable files are:

  • app/main.py
  • app/api/router.py
  • app/api/routers/*.py
  • app/services/*.py
  • app/agents/teacher_agent.py
  • db/bootstrap.sql
  • db/migrations/*.sql
  • docs/architecture/*.md
  • docs/runbooks/*.md
  • docs/contributing/documentation-policy.md

What is stale today

The repo contains multiple documents whose claims are no longer consistent with current code or the newer docs policy.

File Stale claim Current repo evidence
docs/10_current_state/api_inventory.md Says the base path is /api and the quiz router is not registered app/main.py includes api_router with no /api prefix, and app/api/router.py includes quiz.router
docs/00_overview/start_here.md Says request ID middleware and rate limiting are not registered, and that metrics routes do not exist app/main.py adds both middleware classes, and app/api/router.py includes metrics.router
docs/00_overview/start_here.md Says background jobs are not implemented and no scripts/ directory exists app/services/background_jobs.py exists and is started from app/main.py
docs/90_ops/current_cycle_plan.md Says admin auth still relies on X-Admin-Key and RLS is not implemented app/core/auth.py requires admin JWT role, and RLS migrations already exist under db/migrations/20260216000006_*, 20260216000009_*, and later files
docs/90_ops/progress.md Says hybrid search is upcoming and the current focus is frontend integration app/services/retrieval_pipeline.py already implements hybrid retrieval, and the newer docs scope is explicitly backend-only
docs/90_ops/implementation_status.md Says quiz routing is not wired and chat/scraper integration are still pending app/api/router.py registers the quiz router, and test files exist for chat, quiz, and scraping routes
docs/30_design/backend_architecture.md Says quiz router is not included in the API router app/api/router.py includes quiz.router
postman/README.md Postman config states JWT is standard auth app/core/auth.py exposes JWT-based admin authorization
intutype_backend_source_of_truth.md Declares itself the single source of truth for backend architecture docs/index.md and docs/contributing/documentation-policy.md define a different current authority model

What is duplicated today

The branch currently duplicates several documentation and governance surfaces.

Duplicate area Locations What is duplicated
Architecture docs docs/30_design/ and docs/architecture/ Current-system descriptions exist in both old and new structures
Runbooks docs/20_runbooks/ and docs/runbooks/ Local development, deployment, troubleshooting, and operations guidance
Contributor workflow docs root CONTRIBUTING.md, docs/contributing/, and docs/90_ops/ai_workflow.md Workflow, documentation rules, and review expectations
Current-state docs docs/10_current_state/, docs/90_ops/, and docs/current-state.md Multiple “what is true now” narratives
ADR storage docs/90_ops/decisions/ and docs/adr/ Historical ADRs and a new reserved ADR directory
Implementation history docs/90_ops/, docs/Artifacts/, and docs/implementation/ Change history and execution records are spread across three places
Plan docs docs/plans/gh-*.md and docs/plans/issue-*.md Two issue-based naming schemes for the same issue range
API testing docs docs/Postman/ and postman/README.md Human-facing Postman guidance in two places
Source-of-truth claims intutype_backend_source_of_truth.md and docs/contributing/documentation-policy.md Competing statements about which documents outrank code and migrations

What is planned for replacement

The current repo already contains explicit evidence that some older structures are being displaced by newer ones.

Current item Replacement direction already present in repo Evidence
docs/90_ops/ and docs/99_archive/ as primary navigation Historical only; newer active docs tree is intended to carry the live backend narrative docs/index.md says those directories are historical material, not primary navigation
Historical implementation history in docs/90_ops/ and docs/Artifacts/ New implementation records under docs/implementation/ docs/implementation/README.md says new implementation summaries should go there
Historical ADRs in docs/90_ops/decisions/ New ADRs under docs/adr/ docs/adr/README.md says the directory is reserved for ADRs going forward
Mixed issue-plan naming gh-####-<slug>.md as the preferred issue-bound plan convention docs/plans/README.md says gh-####-<slug>.md is the preferred convention and older issue-<number>-<slug>.md files may still exist
Older numbered architecture and runbook trees Newer docs/architecture/, docs/runbooks/, and docs/contributing/ trees mkdocs.yml and docs/index.md now navigate to the newer layout
Ad hoc issue closeout notes Required issue-linked plan docs and implementation docs docs/contributing/documentation-policy.md and docs/contributing/issue-lifecycle.md require one plan doc and one implementation doc per issue
Legacy manual upload ingestion path Reference-driven scrape -> handoff -> job -> ingest path as the production path docs/architecture/ingestion.md says the primary path should be treated as the production path and manual upload is an operational escape hatch

Verified caveats that affect the current branch

  • db/bootstrap.sql is not the full current schema; the newer docs explicitly require the ordered migration set as part of the effective database state.
  • render.yaml defines admin-related services in addition to the backend API and docs service, even though the newer docs scope is backend-only.
  • app/services/background_jobs.py currently instantiates WalletReservationService() with no Supabase client and awaits methods that do not exist on the current service class, so that scheduled cleanup path is not aligned with the current wallet service implementation.
  • app/core/config.py still includes compatibility and legacy-oriented settings such as SUPABASE_SERVICE_KEY.