# mrxtheanon/campus_os architecture

> Architecture diagram of the GitHub repository mrxtheanon/campus_os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrxtheanon/campus_os
- Repository: https://github.com/mrxtheanon/campus_os

## Overview

CampusOS is a FastAPI-backed autonomous campus assistant. A student submits a natural-language request; the chat route hands it to the master agent, which classifies and plans work, dispatches specialist agents, and returns their results. The specialist branches cover campus Q&A, events, lab equipment, grievances, reminders, document generation, and library research. Shared infrastructure provides language-model access, campus knowledge retrieval, persistence, scheduling, proactive monitoring, and learning from interactions. The README and sampled files establish these capabilities; unsampled module internals are represented only where their wiring is documented.

Main entry points: [`backend/app/agents/master_agent.py`](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/master_agent.py) (Master agent), [`backend/app/core/database.py`](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/database.py) (Campus database), [`backend/app/core/llm_manager.py`](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/llm_manager.py) (LLM manager), [`backend/app/agents/student_support.py`](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/student_support.py) (Student support)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request orchestration"]
  node_chat["Chat API<br/>[chat.py]"]
  node_master["Master agent<br/>[master_agent.py]"]
  node_planner["Task planner<br/>[task_planner.py]"]
  node_classifier["Intent patterns<br/>[nlp_patterns.py]"]
end

subgraph group_agents["Specialist services"]
  node_support["Student support<br/>[student_support.py]"]
  node_events["Event operations"]
  node_lab["Lab assistance<br/>[lab_assistance.py]"]
  node_grievances["Grievance routing"]
  node_reminders["Reminder agent<br/>[reminder_agent.py]"]
  node_documents["Document generator"]
  node_research["Library research"]
end

subgraph group_knowledge["AI and knowledge"]
  node_llm["LLM manager<br/>[llm_manager.py]"]
  node_rag["Vector retrieval<br/>[vector_store.py]"]
  node_scraper["Research scraper"]
end

subgraph group_campus["Campus operations"]
  node_db[("Campus database<br/>[database.py]")]
  node_models["Domain models<br/>[base.py]"]
  node_scheduler["Reminder scheduler<br/>[scheduler.py]"]
end

subgraph group_learning["Monitoring and learning"]
  node_monitor["Campus monitor<br/>[campus_monitor.py]"]
  node_learning["Learning engine<br/>[learning_engine.py]"]
  node_selflearn["Self-learning"]
end

node_student(("Student"))

node_student -->|"submits query"| node_chat
node_chat -->|"forwards request"| node_master
node_master -->|"classifies intent"| node_classifier
node_master -->|"plans tasks"| node_planner
node_master -->|"dispatches"| node_support
node_master -->|"dispatches"| node_events
node_master -->|"dispatches"| node_lab
node_master -->|"dispatches"| node_grievances
node_master -->|"dispatches"| node_reminders
node_master -->|"dispatches"| node_documents
node_master -->|"dispatches"| node_research
node_master -->|"returns response"| node_chat
node_support -->|"retrieves knowledge"| node_rag
node_support -->|"generates answer"| node_llm
node_research -->|"searches papers"| node_scraper
node_research -->|"summarizes results"| node_llm
node_events -->|"reads and writes"| node_db
node_lab -->|"reads and writes"| node_db
node_grievances -->|"stores tickets"| node_db
node_grievances -->|"schedules escalation"| node_scheduler
node_reminders -->|"schedules reminders"| node_scheduler
node_documents -->|"generates content"| node_llm
node_db -->|"maps domain records"| node_models
node_monitor -->|"checks campus state"| node_db
node_master -->|"updates interaction learning"| node_learning
node_learning -->|"persists memory"| node_db
node_selflearn -->|"adds learned knowledge"| node_rag
node_selflearn -->|"forms learned answer"| node_llm

click node_chat "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/api/chat.py"
click node_master "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/master_agent.py"
click node_planner "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/task_planner.py"
click node_classifier "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/utils/nlp_patterns.py"
click node_support "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/student_support.py"
click node_events "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/event_operations.py"
click node_lab "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/lab_assistance.py"
click node_grievances "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/grievance_routing.py"
click node_reminders "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/reminder_agent.py"
click node_documents "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/document_generator.py"
click node_research "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/library_research.py"
click node_llm "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/llm_manager.py"
click node_rag "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/vector_store.py"
click node_scraper "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/scrapers/research_scraper.py"
click node_db "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/database.py"
click node_models "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/models/base.py"
click node_scheduler "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/scheduler.py"
click node_monitor "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/campus_monitor.py"
click node_learning "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/learning_engine.py"
click node_selflearn "https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/self_learning_engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat,node_master,node_planner,node_classifier toneBlue
class node_support,node_events,node_lab,node_grievances,node_reminders,node_documents,node_research toneAmber
class node_llm,node_rag,node_scraper toneMint
class node_db,node_models,node_scheduler toneRose
class node_monitor,node_learning,node_selflearn,node_student toneIndigo
```

## Components

### Request orchestration

- [Chat API](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Master agent](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/master_agent.py): `backend/app/agents/master_agent.py`
- [Task planner](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/task_planner.py): `backend/app/core/task_planner.py`
- [Intent patterns](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/utils/nlp_patterns.py): `backend/app/utils/nlp_patterns.py`

### Specialist services

- [Student support](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/student_support.py): `backend/app/agents/student_support.py`
- [Event operations](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/event_operations.py): `backend/app/agents/event_operations.py`
- [Lab assistance](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/lab_assistance.py): `backend/app/agents/lab_assistance.py`
- [Grievance routing](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/grievance_routing.py): `backend/app/agents/grievance_routing.py`
- [Reminder agent](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/reminder_agent.py): `backend/app/agents/reminder_agent.py`
- [Document generator](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/document_generator.py): `backend/app/agents/document_generator.py`
- [Library research](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/agents/library_research.py): `backend/app/agents/library_research.py`

### AI and knowledge

- [LLM manager](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/llm_manager.py): `backend/app/core/llm_manager.py`
- [Vector retrieval](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/vector_store.py): `backend/app/core/vector_store.py`
- [Research scraper](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/scrapers/research_scraper.py): `backend/app/scrapers/research_scraper.py`

### Campus operations

- [Campus database](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Domain models](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/models/base.py): `backend/app/models/base.py`
- [Reminder scheduler](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/scheduler.py): `backend/app/core/scheduler.py`

### Monitoring and learning

- [Campus monitor](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/campus_monitor.py): `backend/app/core/campus_monitor.py`
- [Learning engine](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/learning_engine.py): `backend/app/core/learning_engine.py`
- [Self-learning](https://github.com/mrxtheanon/campus_os/blob/main/backend/app/core/self_learning_engine.py): `backend/app/core/self_learning_engine.py`

### Other components

- **Student**

## Connections

- Student → Chat API: submits query
- Chat API → Master agent: forwards request
- Master agent → Intent patterns: classifies intent
- Master agent → Task planner: plans tasks
- Master agent → Student support: dispatches
- Master agent → Event operations: dispatches
- Master agent → Lab assistance: dispatches
- Master agent → Grievance routing: dispatches
- Master agent → Reminder agent: dispatches
- Master agent → Document generator: dispatches
- Master agent → Library research: dispatches
- Master agent → Chat API: returns response
- Student support → Vector retrieval: retrieves knowledge
- Student support → LLM manager: generates answer
- Library research → Research scraper: searches papers
- Library research → LLM manager: summarizes results
- Event operations → Campus database: reads and writes
- Lab assistance → Campus database: reads and writes
- Grievance routing → Campus database: stores tickets
- Grievance routing → Reminder scheduler: schedules escalation
- Reminder agent → Reminder scheduler: schedules reminders
- Document generator → LLM manager: generates content
- Campus database → Domain models: maps domain records
- Campus monitor → Campus database: checks campus state
- Master agent → Learning engine: updates interaction learning
- Learning engine → Campus database: persists memory
- Self-learning → Vector retrieval: adds learned knowledge
- Self-learning → LLM manager: forms learned answer