# agent369ai-cloud/school-operations-agent-platform architecture

> Architecture diagram of the GitHub repository agent369ai-cloud/school-operations-agent-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agent369ai-cloud/school-operations-agent-platform
- Repository: https://github.com/agent369ai-cloud/school-operations-agent-platform

## Overview

This is a FastAPI school-operations backend: school administrators authenticate and provide roster or assignment data, while student chat updates and scheduled reminders support ongoing operations. The assignment path parses a brief, holds ambiguous details as a draft for clarification, and records workflow events; chat messages are routed to student-status intents and published to a live SSE stream. Authentication and tenant checks protect school data, with relational entities and a correlation-ID audit ledger underpinning workflows. Edges reflect shown imports, calls, or README claims; Telegram and submission behavior are represented from the tree and documentation, but their implementation details were not sampled.

Main entry points: [`app/models.py`](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/models.py) (School domain and audit records), [`app/main.py`](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/main.py) (FastAPI app), [`app/routers/chat_mock.py`](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/chat_mock.py) (Chat intent router), [`app/routers/ingestion.py`](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/ingestion.py) (Assignment and roster intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and interfaces"]
  node_main["FastAPI app<br/>[main.py]"]
  node_dashboard["Dashboard page<br/>[dashboard.html]"]
  node_live["SSE updates and timeline<br/>[chat_mock.py]"]
  node_telegram["Telegram webhook"]
  node_telegram_integration["Telegram integration<br/>[telegram.py]"]
  node_envelope["Message envelope<br/>[envelope.py]"]
end

subgraph group_workflow["School workflows"]
  node_chat["Chat intent router<br/>[chat_mock.py]"]
  node_ingestion["Assignment and roster intake<br/>[ingestion.py]"]
  node_parser["Brief parser<br/>[ai_parser.py]"]
  node_schema["Parsed assignment schema<br/>[schemas.py]"]
  node_scheduler["Reminder and policy engine<br/>[scheduler.py]"]
  node_submissions["Submission service"]
end

subgraph group_security["Identity and access"]
  node_auth["School registration and login<br/>[auth.py]"]
  node_auth_deps["Token and role checks<br/>[deps.py]"]
end

subgraph group_state["Data and trace"]
  node_config["Runtime settings<br/>[config.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_models[("School domain and audit records<br/>[models.py]")]
  node_audit["Audit service<br/>[audit.py]"]
end

node_teacher(("Teacher / admin"))
node_student(("Student / messaging client"))
node_llm{{"LLM service"}}

node_main -->|"initializes on startup"| node_database
node_main -->|"mounts router"| node_chat
node_main -->|"mounts router"| node_ingestion
node_main -->|"mounts router"| node_auth
node_main -->|"renders page"| node_dashboard
node_teacher -->|"uploads briefs and rosters"| node_ingestion
node_ingestion -->|"parses brief"| node_parser
node_parser -->|"requests extraction"| node_llm
node_parser -->|"validates result"| node_schema
node_ingestion -->|"triggers reminders"| node_scheduler
node_student -->|"sends message"| node_chat
node_chat -->|"publishes update"| node_live
node_chat -->|"records event"| node_models
node_live -->|"reads timeline"| node_models
node_auth -->|"reads and writes accounts"| node_models
node_auth_deps -->|"uses sessions"| node_database
node_auth_deps -->|"checks user and logs denial"| node_models
node_auth_deps -->|"uses signing settings"| node_config
node_database -->|"creates ORM tables"| node_models
node_audit -->|"uses audit records"| node_models
node_scheduler -->|"uses domain models"| node_models
node_telegram -.-> node_telegram_integration
node_telegram -.-> node_envelope

click node_main "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/main.py"
click node_dashboard "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/templates/dashboard.html"
click node_chat "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/chat_mock.py"
click node_live "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/chat_mock.py"
click node_ingestion "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/ingestion.py"
click node_parser "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/ai_parser.py"
click node_schema "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/schemas.py"
click node_scheduler "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/scheduler.py"
click node_telegram "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/telegram_webhook.py"
click node_telegram_integration "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/integrations/telegram.py"
click node_envelope "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/integrations/envelope.py"
click node_auth "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/auth.py"
click node_auth_deps "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/auth/deps.py"
click node_config "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/config.py"
click node_database "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/database.py"
click node_models "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/models.py"
click node_audit "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/audit.py"
click node_submissions "https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/submission_service.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_main,node_dashboard,node_live,node_telegram,node_telegram_integration,node_envelope,node_student toneBlue
class node_chat,node_ingestion,node_parser,node_schema,node_scheduler,node_submissions toneAmber
class node_auth,node_auth_deps toneMint
class node_config,node_database,node_models,node_audit toneRose
class node_teacher,node_llm toneIndigo
```

## Components

### API and interfaces

- [FastAPI app](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/main.py): `app/main.py`
- [Dashboard page](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/templates/dashboard.html): `app/templates/dashboard.html`
- [SSE updates and timeline](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/chat_mock.py): `app/routers/chat_mock.py`
- [Telegram webhook](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/telegram_webhook.py): `app/routers/telegram_webhook.py`
- [Telegram integration](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/integrations/telegram.py): `app/integrations/telegram.py`
- [Message envelope](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/integrations/envelope.py): `app/integrations/envelope.py`

### School workflows

- [Chat intent router](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/chat_mock.py): `app/routers/chat_mock.py`
- [Assignment and roster intake](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/ingestion.py): `app/routers/ingestion.py`
- [Brief parser](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/ai_parser.py): `app/services/ai_parser.py`
- [Parsed assignment schema](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/schemas.py): `app/schemas.py`
- [Reminder and policy engine](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/scheduler.py): `app/services/scheduler.py`
- [Submission service](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/submission_service.py): `app/services/submission_service.py`

### Identity and access

- [School registration and login](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Token and role checks](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/auth/deps.py): `app/auth/deps.py`

### Data and trace

- [Runtime settings](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/config.py): `app/config.py`
- [Database sessions](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/database.py): `app/database.py`
- [School domain and audit records](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/models.py): `app/models.py`
- [Audit service](https://github.com/agent369ai-cloud/school-operations-agent-platform/blob/main/app/services/audit.py): `app/services/audit.py`

### Other components

- **Teacher / admin**
- **Student / messaging client**
- **LLM service**

## Connections

- FastAPI app → Database sessions: initializes on startup (evidence: `app/main.py`)
- FastAPI app → Chat intent router: mounts router (evidence: `app/main.py`)
- FastAPI app → Assignment and roster intake: mounts router (evidence: `app/main.py`)
- FastAPI app → School registration and login: mounts router (evidence: `app/main.py`)
- FastAPI app → Dashboard page: renders page (evidence: `app/main.py`)
- Teacher / admin → Assignment and roster intake: uploads briefs and rosters (evidence: `README.md`)
- Assignment and roster intake → Brief parser: parses brief (evidence: `app/routers/ingestion.py`)
- Brief parser → LLM service: requests extraction (evidence: `app/services/ai_parser.py`)
- Brief parser → Parsed assignment schema: validates result (evidence: `app/services/ai_parser.py`)
- Assignment and roster intake → Reminder and policy engine: triggers reminders (evidence: `app/routers/ingestion.py`)
- Student / messaging client → Chat intent router: sends message (evidence: `README.md`)
- Chat intent router → SSE updates and timeline: publishes update (evidence: `app/routers/chat_mock.py`)
- Chat intent router → School domain and audit records: records event (evidence: `app/routers/chat_mock.py`)
- SSE updates and timeline → School domain and audit records: reads timeline (evidence: `app/routers/chat_mock.py`)
- School registration and login → School domain and audit records: reads and writes accounts (evidence: `app/routers/auth.py`)
- Token and role checks → Database sessions: uses sessions (evidence: `app/auth/deps.py`)
- Token and role checks → School domain and audit records: checks user and logs denial (evidence: `app/auth/deps.py`)
- Token and role checks → Runtime settings: uses signing settings (evidence: `app/auth/deps.py`)
- Database sessions → School domain and audit records: creates ORM tables (evidence: `app/database.py`)
- Audit service → School domain and audit records: uses audit records (evidence: `app/services/audit.py`)
- Reminder and policy engine → School domain and audit records: uses domain models (evidence: `app/services/scheduler.py`)
- Telegram webhook → Telegram integration
- Telegram webhook → Message envelope
