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 SPA's shared UI vocabulary - the type scale and its font-size-adjust, the control scale and touch tap areas, the settings row grammar, the selected-state fill, StatusPill, TextLink, Button and the per-row control names, the Popover/Select/Menu dropdown family, focus between an opener and the view it opens (lib/viewFocus.ts, the side panel, the panel scope), grey ink on light grounds and fills, and the lint guards that keep each of them the only one |
| Agent & Retrieval System | Agentic RAG pipeline, the registered tool surface (search, find_entity, read_file plus the inventory and connector tools), attachment handling, knowledge routing, the conversation history budget and its stored summary, streaming events, the turn timeline (blocks, notes and round lines) and the trace rows' words |
| Agent Skills | Markdown instruction bodies the agent loads on demand - the Skill / SkillVersion / SkillDraft ownership split, the shipped registry and its boot sync, the Settings page (drafts, publishing and lint, versions, shipped updates, export and import, archive), the audience rules and budgets, the use_skill tool, and the per-turn SkillUse record |
| Artifacts | Documents, quizzes, flashcards and slide decks the assistant makes beside the chat: the Artifact/ArtifactVersion/ArtifactDraft/ArtifactRender models, the kind contract and the ArtifactContent union, the two tools and the artifact_start/artifact_delta/artifact_end events, the turn's catalog and active-body context, drafts and their promotion moments, the cc_artifacts flag, the owner-scoped API, the export pipeline with its destinations, the render pipeline that draws a deck's pages, the panel viewer with its editors, take and study modes, library and print page |
| Connector System | Plugin architecture for external service integrations (OAuth2, actions and their human labels, the write confirmation card and receipt, cloud drive imports, per-deployment availability, per-institution manifests) |
| 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, the environment-to-institution map, setup wizard, dynamic branding, and agent prompt templating |
| Subdomain Provisioning | Automatic {env}.campuscoreai.com subdomain + ACM SSL, custom domain two-path SSL modes, the custom-domain state machine and the deletion of failed certificates |
| 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 Models tool that picks the agent's model and edits the 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, what a guest receives of a turn, why the conversations outlive them, and the rate-limit posture |
| Website Widget | The embeddable chat bubble: the one-line script tag, the loader and its frame, the signed cookie-less session, the frame-ancestors allow-list, the Settings tab, and the accent-colour exception to the branding rule |
| 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), every environment's encrypted CloudTrail stream, the daily findings report for the pilot and its known-findings file, 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 |
| The cc Command Line | The host-side cc tool in cli/ - installing it and why it needs a shell alias, the four commands, what cc deploy refuses and why it pushes origin/main without tagging, how the local branches are brought up to the deployed commit, and how scripts/cli-checks.sh runs in the gate, pre-commit, and CI |
| 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; tests keep SQS in memory and use their own bucket |
| 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), sub-step spans and the timing service, the Pipeline Manager dashboard and per-document run timing |
| 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 S3 and SQS endpoint fields and the typed S3_SERVER setting, the deploy-contract check, and where values live per environment |
| Dependency-Direction Audit | A dated, archived 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.