# vidyaschool/school-app architecture

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

- Interactive diagram: https://gitdiagram.com/vidyaschool/school-app
- Repository: https://github.com/vidyaschool/school-app

## Overview

VidyaSchool is a multi-platform school ERP: people use web and mobile portals to access role-specific school services, with a FastAPI service implementing shared workflows and PostgreSQL-backed state. The public portal also serves school information, while the admin portal handles governance and content management. The README documents chat, fees, attendance, library, notices, documents, AI page building, and QR authentication; several route implementations were not sampled, so those capability links are documented rather than inferred from code. The desktop client is described as a QR/OAuth authentication client.

Main entry points: [`backend/main.py`](https://github.com/vidyaschool/school-app/blob/main/backend/main.py) (FastAPI service), [`backend/app/core/database.py`](https://github.com/vidyaschool/school-app/blob/main/backend/app/core/database.py) (PostgreSQL database), [`backend/app/routes/fees.py`](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/fees.py) (Fees and payments), [`backend/app/routes/search.py`](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/search.py) (School search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Web portals"]
  node_school_portal["Public portal"]
  node_role_portals["Role portals"]
  node_admin_portal["Admin portal"]
  node_web_api["Web API routes"]
  node_admin_api["Admin API routes"]
end

subgraph group_service["Backend service"]
  node_backend_app["FastAPI service<br/>[main.py]"]
  node_auth["Authentication and RBAC<br/>[auth.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("PostgreSQL database<br/>[database.py]")]
  node_cache[("Cache service<br/>[cache.py]")]
end

subgraph group_capabilities["School workflows"]
  node_admin_workflows["Admin governance<br/>[admin.py]"]
  node_fees["Fees and payments<br/>[fees.py]"]
  node_substitutions["Teacher substitutions"]
  node_search["School search<br/>[search.py]"]
  node_chat["Real-time chat<br/>[chats.py]"]
  node_library["Library management<br/>[library.py]"]
  node_teacher_services["Teacher services<br/>[teacher.py]"]
  node_documents["Documents and notes<br/>[documents.py]"]
  node_notices["Notices and announcements<br/>[notices.py]"]
  node_page_builder["AI page builder<br/>[page_builder_ai.py]"]
end

subgraph group_clients["Other clients"]
  node_desktop["Desktop auth client<br/>[main.cpp]"]
  node_mobile["Mobile apps"]
end

node_visitors(("School visitors"))
node_postgres[("PostgreSQL")]
node_razorpay["Razorpay"]
node_cloud_storage["AWS S3 storage"]

node_visitors -->|"browse"| node_school_portal
node_role_portals -.->|"request services"| node_web_api
node_admin_portal -.->|"manage school"| node_admin_api
node_web_api -.->|"proxy API"| node_backend_app
node_admin_api -.->|"call service"| node_backend_app
node_backend_app -->|"uses security"| node_auth
node_backend_app -->|"registers routes"| node_admin_workflows
node_backend_app -->|"registers routes"| node_fees
node_backend_app -->|"registers routes"| node_substitutions
node_backend_app -->|"registers routes"| node_search
node_backend_app -->|"registers routes"| node_chat
node_backend_app -->|"registers routes"| node_library
node_backend_app -->|"registers routes"| node_teacher_services
node_backend_app -.->|"serves documents"| node_documents
node_backend_app -->|"registers routes"| node_notices
node_backend_app -.->|"serves page builder"| node_page_builder
node_admin_workflows -->|"queries state"| node_database
node_fees -.->|"reads and writes"| node_database
node_fees -->|"processes payments"| node_razorpay
node_fees -->|"stores receipts"| node_cloud_storage
node_substitutions -->|"loads domain data"| node_models
node_search -->|"queries pages"| node_database
node_search -->|"caches results"| node_cache
node_chat -.->|"uses persisted data"| node_database
node_library -.->|"manages catalog"| node_database
node_teacher_services -.->|"uses school records"| node_database
node_documents -->|"hosts materials"| node_cloud_storage
node_notices -.->|"stores notices"| node_database
node_page_builder -.->|"stores pages"| node_database
node_backend_app -->|"persists data"| node_postgres
node_desktop -->|"authenticates"| node_backend_app
node_mobile -->|"uses services"| node_backend_app
node_mobile -->|"registers push tokens"| node_backend_app

click node_school_portal "https://github.com/vidyaschool/school-app/tree/main/frontend/app/(static_pages)"
click node_role_portals "https://github.com/vidyaschool/school-app/tree/main/frontend/app/student/%5Busername%5D"
click node_admin_portal "https://github.com/vidyaschool/school-app/tree/main/admin_frontend/app/admin/%5Busername%5D"
click node_web_api "https://github.com/vidyaschool/school-app/tree/main/frontend/app/api"
click node_admin_api "https://github.com/vidyaschool/school-app/tree/main/admin_frontend/app/api"
click node_backend_app "https://github.com/vidyaschool/school-app/blob/main/backend/main.py"
click node_auth "https://github.com/vidyaschool/school-app/blob/main/backend/app/core/auth.py"
click node_models "https://github.com/vidyaschool/school-app/blob/main/backend/app/models.py"
click node_database "https://github.com/vidyaschool/school-app/blob/main/backend/app/core/database.py"
click node_cache "https://github.com/vidyaschool/school-app/blob/main/backend/app/core/cache.py"
click node_admin_workflows "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/admin.py"
click node_fees "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/fees.py"
click node_substitutions "https://github.com/vidyaschool/school-app/blob/main/backend/app/core/substitution_engine.py"
click node_search "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/search.py"
click node_chat "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/chats.py"
click node_library "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/library.py"
click node_teacher_services "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/teacher.py"
click node_documents "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/documents.py"
click node_notices "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/notices.py"
click node_page_builder "https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/page_builder_ai.py"
click node_desktop "https://github.com/vidyaschool/school-app/blob/main/desktop/main.cpp"
click node_mobile "https://github.com/vidyaschool/school-app/tree/main/mobile-app"

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_school_portal,node_role_portals,node_admin_portal,node_web_api,node_admin_api toneBlue
class node_backend_app,node_auth,node_models,node_database,node_cache,node_postgres,node_cloud_storage toneAmber
class node_admin_workflows,node_fees,node_substitutions,node_search,node_chat,node_library,node_teacher_services,node_documents,node_notices,node_page_builder toneMint
class node_desktop,node_mobile toneRose
class node_visitors,node_razorpay toneIndigo
```

## Components

### Web portals

- [Public portal](https://github.com/vidyaschool/school-app/tree/main/frontend/app/(static_pages)): `frontend/app/(static_pages)`
- [Role portals](https://github.com/vidyaschool/school-app/tree/main/frontend/app/student/%5Busername%5D): `frontend/app/student/[username]`
- [Admin portal](https://github.com/vidyaschool/school-app/tree/main/admin_frontend/app/admin/%5Busername%5D): `admin_frontend/app/admin/[username]`
- [Web API routes](https://github.com/vidyaschool/school-app/tree/main/frontend/app/api): `frontend/app/api`
- [Admin API routes](https://github.com/vidyaschool/school-app/tree/main/admin_frontend/app/api): `admin_frontend/app/api`

### Backend service

- [FastAPI service](https://github.com/vidyaschool/school-app/blob/main/backend/main.py): `backend/main.py`
- [Authentication and RBAC](https://github.com/vidyaschool/school-app/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Domain models](https://github.com/vidyaschool/school-app/blob/main/backend/app/models.py): `backend/app/models.py`
- [PostgreSQL database](https://github.com/vidyaschool/school-app/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Cache service](https://github.com/vidyaschool/school-app/blob/main/backend/app/core/cache.py): `backend/app/core/cache.py`

### School workflows

- [Admin governance](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/admin.py): `backend/app/routes/admin.py`
- [Fees and payments](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/fees.py): `backend/app/routes/fees.py`
- [Teacher substitutions](https://github.com/vidyaschool/school-app/blob/main/backend/app/core/substitution_engine.py): `backend/app/core/substitution_engine.py`
- [School search](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/search.py): `backend/app/routes/search.py`
- [Real-time chat](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/chats.py): `backend/app/routes/chats.py`
- [Library management](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/library.py): `backend/app/routes/library.py`
- [Teacher services](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/teacher.py): `backend/app/routes/teacher.py`
- [Documents and notes](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/documents.py): `backend/app/routes/documents.py`
- [Notices and announcements](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/notices.py): `backend/app/routes/notices.py`
- [AI page builder](https://github.com/vidyaschool/school-app/blob/main/backend/app/routes/page_builder_ai.py): `backend/app/routes/page_builder_ai.py`

### Other clients

- [Desktop auth client](https://github.com/vidyaschool/school-app/blob/main/desktop/main.cpp): `desktop/main.cpp`
- [Mobile apps](https://github.com/vidyaschool/school-app/tree/main/mobile-app): `mobile-app`

### Other components

- **School visitors**
- **PostgreSQL**
- **Razorpay**
- **AWS S3 storage**

## Connections

- School visitors → Public portal: browse (evidence: `README.md`)
- Role portals → Web API routes: request services (evidence: `README.md`)
- Admin portal → Admin API routes: manage school (evidence: `README.md`)
- Web API routes → FastAPI service: proxy API (evidence: `README.md`)
- Admin API routes → FastAPI service: call service (evidence: `README.md`)
- FastAPI service → Authentication and RBAC: uses security (evidence: `backend/main.py`)
- FastAPI service → Admin governance: registers routes (evidence: `backend/main.py`)
- FastAPI service → Fees and payments: registers routes (evidence: `backend/main.py`)
- FastAPI service → Teacher substitutions: registers routes (evidence: `backend/main.py`)
- FastAPI service → School search: registers routes (evidence: `backend/main.py`)
- FastAPI service → Real-time chat: registers routes (evidence: `backend/main.py`)
- FastAPI service → Library management: registers routes (evidence: `backend/main.py`)
- FastAPI service → Teacher services: registers routes (evidence: `backend/main.py`)
- FastAPI service → Documents and notes: serves documents (evidence: `README.md`)
- FastAPI service → Notices and announcements: registers routes (evidence: `backend/main.py`)
- FastAPI service → AI page builder: serves page builder (evidence: `README.md`)
- Admin governance → PostgreSQL database: queries state (evidence: `backend/app/routes/admin.py`)
- Fees and payments → PostgreSQL database: reads and writes (evidence: `README.md`)
- Fees and payments → Razorpay: processes payments (evidence: `README.md`)
- Fees and payments → AWS S3 storage: stores receipts (evidence: `README.md`)
- Teacher substitutions → Domain models: loads domain data (evidence: `backend/app/core/substitution_engine.py`)
- School search → PostgreSQL database: queries pages (evidence: `backend/app/routes/search.py`)
- School search → Cache service: caches results (evidence: `backend/app/routes/search.py`)
- Real-time chat → PostgreSQL database: uses persisted data (evidence: `README.md`)
- Library management → PostgreSQL database: manages catalog (evidence: `README.md`)
- Teacher services → PostgreSQL database: uses school records (evidence: `README.md`)
- Documents and notes → AWS S3 storage: hosts materials (evidence: `README.md`)
- Notices and announcements → PostgreSQL database: stores notices (evidence: `README.md`)
- AI page builder → PostgreSQL database: stores pages (evidence: `README.md`)
- FastAPI service → PostgreSQL: persists data (evidence: `README.md`)
- Desktop auth client → FastAPI service: authenticates (evidence: `README.md`)
- Mobile apps → FastAPI service: uses services (evidence: `README.md`)
- Mobile apps → FastAPI service: registers push tokens (evidence: `backend/main.py`)
