Project Documentation¶
Technical documentation for CampusCore developers. Each doc covers a major feature or subsystem.
Contents¶
| Doc | Description |
|---|---|
| Architecture Overview (client-facing) | The high-level component diagram we share with universities - Mermaid source, box-to-code mapping, data boundary talking points, and the branded PNG export for decks |
| AWS Resource Architecture (client-facing) | The AWS resource diagram behind the overview - everything a standard deployment's Terraform provisions from network to compute, box-to-Terraform mapping, the optional-resource switches, schedule and alarm tables, and the committed draw.io source whose PNG export is the diagram everywhere |
| SPA & Typed API Framework | The React 19 + TypeScript SPA (web/), the @api_endpoint JSON/SSE framework (campus_core/api/), the OpenAPI -> generated-types contract pipeline and its CI drift gate, and how the bundle is served |
| SPA Design System | The Popover primitive and the Select/Menu dropdown components - placement and flip, dismissal, sizes, option semantics, and the lint guard that keeps native selects out |
| Agent & Retrieval System | Agentic RAG pipeline, two retrieval tools (search_attachments vs search_knowledge), attachment handling, knowledge routing, streaming events |
| Connector System | Plugin architecture for external service integrations (OAuth2, actions, cloud drive imports) |
| Connector Philosophy | The why behind how we build connectors — hand-roll vs. MCP, action surface curation, return shapes, versioning, permission gating |
| Settings Page | The settings SPA surface: one content column, the tab table and its gates, and where the shared UI pieces live |
| Branding & Theming | The color token architecture (fixed CampusCore brand, school tokens for identity surfaces, the warm ink dark scale), the three branding image assets (logo, login background, favicon) and their validation, the /favicon.ico route, the composed tab title, and the bootstrap freshness contract |
| Multi-Client Architecture | BYOC deployment model, setup wizard, dynamic branding, and agent prompt templating |
| Subdomain Provisioning | Automatic {env}.campuscoreai.com subdomain + ACM SSL, custom domain two-path SSL modes |
| HTMX Auth Pattern | HTMX-safe auth decorators (HX-Redirect instead of 302) to prevent full-page swaps into partial targets |
| User Identity | Official name (IdP-owned, resynced every SSO login) vs the user-owned preferred name, and how SSO linkage is detected |
| Audit Logging | The audit trail end-to-end - event taxonomy, the two delivery tiers, the admin-facing settings tab and CSV export, the Object-Locked S3 archive, and the per-tenant AWS logging stack |
| Usage Analytics | The admin-facing Analytics tab - nightly rollup fact tables, metric semantics, replica-aware recompute, aggregate-only privacy posture |
| Model Usage and Cost Tracking | The pricing registry, the one metered call path, and the client-facing model-cost dashboard |
| Observability Stack | Architecture overview — where errors / metrics / traces / logs go, and how Sentry, CloudWatch, Slack notifications, and the in-app admins fit together |
| Availability Measurement | How availability is tracked and the percentage calculated - the Route 53 readiness probe, the formula and its reproducible CloudWatch queries, the availability dashboard, and the maintenance-window log |
| Agent Observability | OTel-based agent tracing — GenAI-conventions span hierarchy, agent-run filtering, PostgreSQL admin storage, Sentry bridge, golden-signal metrics |
| Vector Index Observability | pgvector / HNSW health dashboard at /admin/observability/vector/, the five metrics, EventBridge auto-rebuild schedule, maintenance log + runbook |
| Public Access (guest chat) | Chat without signing in: the two publish switches (public folder tier, per-scrape-source flag), the deployment-scoped feature gate, guest sessions and their janitor, and the rate-limit posture |
| Knowledge Access Control | Who a read runs as - the three identity types, the single conversion that raises rather than substituting one, which layer takes which type, why agent tools are bound at construction, and why the Postgres floor is built but not enabled |
| Security & SOC 2 Compliance | Encryption at rest/in transit, WAF at the ALB edge, the optional AWS security posture bundle (GuardDuty, Config, Security Hub, Inspector), FERPA data handling, the operator-vs-institution access model, Sentry PII scrubber, Fernet credential encryption, CI policy enforcement |
| RBAC & Feature Flags | SSO-driven roles, role-scoped knowledge folders, two-axis feature flags (CampusCore-availability + institution-enablement), platform-vs-institution admin boundary |
| Local Canvas Testing | Run a real Canvas LMS in the dev stack - stack.sh up --canvas - with Keycloak-shared personas, seeded coursework, and the connector pre-configured, to drive agent read/write scenarios end to end |
| Local SSO Testing (Keycloak) | Spin up a spec-compliant OIDC/SAML IdP - per worktree stack via stack.sh up --sso, or on the main checkout via the compose sso profile - to exercise the real login + group→role sync paths for both protocols |
| Parallel Dev Stacks | Per-worktree isolated dev stacks via scripts/stack.sh - own containers, ports, DB, worker, and cc-<slug>.localhost hostname; volume-clone seeding from the main stack |
| PostgreSQL Version Upgrades | Runbook for moving a client's database to a new major version with a seconds-long switchover - where the version is declared, the one-time reboot older instances need, the prepare/switchover/abort workflow, and why an application deploy must not land mid-window |
| VPC Migration Cutover | One-time per-client runbook for moving an environment off the AWS default VPC onto its dedicated VPC - what replaces and why there is downtime, the scripted RDS snapshot-restore, and the targeted-apply cutover sequence |
| RDS Configuration | The per-environment database knobs (storage, autoscaling ceiling, instance class, backup retention, read replica) - the GitHub-variable to TF_VAR chain and its single-default rule, how each change applies (immediate, Blue/Green, at birth), and the read-replica path end to end |
| Adding a Feature Flag | Developer how-to: register, sync, gate, and test a new feature flag end-to-end |
| Web Scraping & Crawl Modes | The WebPage queue model, the eight scrape modes and their flag semantics, PathScope path filtering, and how a crawl run reaches the ingest pipeline |
| Document Pipeline | Full design for the ingest pipeline — load envelopes, decisions (Modal/Lambda → in-process Fargate, two-queue priority, S3-staging, read replica, rate budget), target architecture, phasing |
| Ingest State Machine | Engineer reference: step diagram, error categories, retry semantics, how to add a new step |
| Runtime Verification | Why static checks don't prove the system runs, and a pointer to the runtime_validation skill that owns the runnable per-surface recipes (stack-up, real-HTTP UI/endpoint checks, SSE agent, upload pipeline, Terraform) |
| Environment Configuration | The typed Settings model as single source of truth for env vars, cloud_required deploy metadata, the deploy-contract check, and where values live per environment |
| Dependency-Direction Audit | Contract-ownership audit of the core backend subsystems - severity-ranked findings register (spawned refactor issues #13-#22), compliant reference seams, per-component context |
Docs are added incrementally as features are built or updated.