Skip to content

Architecture Overview (client-facing)

This is the high-level system diagram we share with universities. It deliberately hides inner workings: boxes are components, arrows describe behavior between them, and nothing below the component level appears. For the engineering-depth view of any subsystem, follow the deep docs indexed in README.md. For the AWS resources that back these components - network, compute, data, and the optional pieces per deployment - see the companion AWS Resource Architecture.

The diagram

flowchart TD
  subgraph community["  Campus community  "]
    direction LR
    users["Students, faculty & staff"]
    guests["Public visitors"]
  end

  idp["Campus identity provider"]

  subgraph deployment["  CampusCore deployment - dedicated AWS environment per university  "]
    spa["Frontend"]
    subgraph backend["  Backend system  "]
      agent["AI Agent"]
    end
    kb[("Knowledge base<br/><i>PostgreSQL + pgvector</i>")]
    files[("Object storage (S3)")]

    subgraph ingestion["  Content ingestion  "]
      scraper["Web scraper"]
      connectors["Connectors<br/><i>Canvas · ServiceNow ·<br/>Gmail · Google Calendar · Google Drive ·<br/>Outlook · OneDrive · SharePoint ·<br/>PostgreSQL · S3 buckets</i>"]
      pipeline["Ingestion pipeline<br/><i>queues + workers</i>"]
    end
  end

  subgraph sources["  Campus content sources  "]
    direction LR
    web["Campus websites"]
    uploads["Documents & files"]
    systems["Campus systems"]
  end

  subgraph providers["  AI model providers  "]
    direction LR
    openai["OpenAI"]
    google["Google"]
    cohere["Cohere<br/><i>planned</i>"]
  end

  users -- "sign in through campus SSO" --> idp
  idp -- "asserts identity<br/>(SAML / OIDC)" --> backend
  users -- "ask questions, upload<br/>documents, administer" --> spa
  guests -- "ask questions without an account<br/>(optional, enabled per school)" --> spa
  spa -- "calls typed APIs; answers stream<br/>back live with source citations" --> backend
  agent -- "hybrid semantic +<br/>keyword search;<br/>access rules enforced<br/>on every query" --> kb
  agent -- "sends question + retrieved context;<br/>receives the generated answer" --> providers

  web -- "crawled on a schedule" --> scraper
  uploads -- "uploaded in the app or<br/>attached to conversations" --> pipeline
  systems -- "ingested via APIs or file stores,<br/>e.g. Google Drive, Canvas" --> connectors
  scraper -- "queues discovered pages" --> pipeline
  connectors -- "queues synced content" --> pipeline
  pipeline -- "keeps original files" --> files
  pipeline -- "extracts, chunks, embeds,<br/>and indexes content" --> kb
  pipeline -- "embedding & OCR<br/>during ingestion" --> providers

  classDef ccPeople fill:#f1f5f9,stroke:#94a3b8,color:#0f172a
  classDef ccCloud fill:#eff6ff,stroke:#3b82f6,color:#0f172a
  classDef ccExternal fill:#fffbeb,stroke:#d97706,color:#0f172a
  classDef ccBoundary fill:#f8fafc,stroke:#cbd5e1,color:#475569
  classDef ccCloudBoundary fill:#f5f9ff,stroke:#3b82f6,stroke-width:2px,color:#1d4ed8
  classDef ccInnerBoundary fill:#ffffff,stroke:#93c5fd,color:#3b82f6
  class users,guests,web,uploads,systems ccPeople
  class spa,agent,kb,files,scraper,connectors,pipeline ccCloud
  class idp,openai,google,cohere ccExternal
  class community,sources,providers ccBoundary
  class deployment ccCloudBoundary
  class ingestion,backend ccInnerBoundary

Reading the diagram

The diagram encodes its claims in three colors and one nesting.

  • The blue boundary is the whole product: one dedicated AWS environment per university, owned by that university. This is the BYOC deployment model; multi-client-architecture.md covers it in depth.
  • Amber boxes are external services: the university's own identity provider and the AI model providers.
  • Slate boxes are the university's people and content - everything CampusCore serves and ingests, but does not own.
  • The AI Agent sits inside the Backend system box because it is not a separately deployed service; it runs inside the backend.
  • Arrow labels carry the behavior; box labels are only component names.

What each component maps to in the code

Each box resolves to a concrete code home. One diagram entry is deliberately ahead of the code: Cohere is labeled planned because the code today integrates OpenAI and Google Gemini only (apps/main_app/clients/).

Diagram box Code
Frontend campuscore_app/web/ (React SPA)
Backend system campuscore_app/campus_core/ + apps/main_app/ (Django)
AI Agent apps/main_app/services/agent/ (AgentCore ReAct loop)
Knowledge base PostgreSQL + pgvector, searched via DocumentChunkVectorStore
Object storage (S3) S3 client factories in apps/main_app/clients/aws.py; originals kept by the ingestion pipeline
Web scraper apps/main_app/services/scraping/
Connectors apps/connectors/connectors/ - registry keys: canvas, gmail, google-calendar, google-drive, outlook-mail, outlook-calendar, onedrive, sharepoint, postgres, s3-bucket, servicenow. Banner is doc-only, no code yet; see connectors.md
Ingestion pipeline apps/main_app/services/document_ingestion/ (see document-pipeline.md)

Data boundary talking points

These are the four points the diagram is built to support in client conversations.

  • One university, one environment: each institution gets its own deployment in an AWS account it owns; nothing is shared between universities.
  • Encrypted everywhere: data is encrypted at rest and in transit across the platform; security-and-compliance.md is the reference.
  • Campus sign-on, campus access rules: authentication runs through the university's identity provider, and content permissions follow the user into every answer; knowledge-access-control.md describes the enforcement.
  • AI models see only what's needed: questions and retrieved passages go to the model providers to compose answers. Whether providers may use that data for training is governed by their enterprise API terms - check the current OpenAI and Google terms, or the signed DPA, before stating this to a client.

Exporting a PNG for a client deck

assets/architecture-export.html is a standalone page that renders this diagram with brand styling: Nunito, CampusCore blue, the deployment title anchored to the bottom of its box, and a color legend. The export needs internet access - the page loads Mermaid and the Nunito font from CDNs, and shows a red failure banner in the output if either fails. Render it to a 2x PNG with headless Chrome, from the repo root:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless=new --disable-gpu --hide-scrollbars \
  --user-data-dir=/tmp/cc-arch-export-profile \
  --window-size=1720,1260 --force-device-scale-factor=2 \
  --virtual-time-budget=15000 \
  --screenshot=/tmp/campuscore-architecture.png \
  "file://$(pwd)/docs/project/assets/architecture-export.html"

The PNG is complete once it appears at /tmp/campuscore-architecture.png; the Chrome process may never exit on its own, so kill it once the file is there.

Where this diagram is published

The client docs portal serves a client-worded page, product/architecture-overview.md, which pulls the diagram from this file via a snippet include - the Mermaid block between the --8<-- markers above is the single Markdown source. The Mermaid source still exists twice overall: here (rendered by GitHub and the docs site) and in the export page (so the deck PNG carries the brand styling). If you change the diagram, change both.