# deepak4124/campus-admin architecture

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

- Interactive diagram: https://gitdiagram.com/deepak4124/campus-admin
- Repository: https://github.com/deepak4124/campus-admin

## Overview

1. This repository is a two-tier monorepo: a Python API in `backend/` and a Next.js web app in `frontend/`. The README explicitly says it is a scaffold, so the architecture is defined more by boundaries and wiring than by business logic.

2. The primary external dependency is Supabase. It is planned to provide authentication and storage, and both sides of the repo have Supabase integration points: backend core modules under `backend/app/core/` and a frontend client in `frontend/src/lib/supabase.ts`.

3. The backend is a FastAPI service. `backend/app/main.py` is the application entrypoint, and `backend/requirements.txt` plus `uvicorn app.main:app --reload --app-dir backend` define the runtime. This backend is the API boundary for school-admin operations.

4. Backend code is organized in a standard layered shape:
   - `routes/` exposes HTTP endpoints
   - `services/` holds domain/business operations
   - `schemas/` defines request/response models
   - `core/` contains shared infrastructure concerns such as auth and Supabase wiring  
   This separation is the main backend architectural boundary.

5. The backend domain is split into four areas, each with matching route, service, and schema modules: `application`, `attendance`, `directory`, and `receipt`. That suggests the API surface is centered around student/faculty operations, attendance workflows, and fee/receipt handling.

6. There is also a dedicated `email_service.py`, which indicates outbound email is treated as its own integration boundary rather than being embedded inside route handlers. In an architecture diagram, this should be shown as a backend-side external integration.

7. The frontend is a Next.js app using the App Router. The main structure is under `frontend/src/app/`, with pages for `dashboard`, `students`, `faculty`, `student-attendance`, `faculty-attendance`, `fee-management`, `reports`, and `check-in-audit`. Shared app shell files include `layout.tsx`, `globals.css`, and `components.tsx`.

8. Authentication on the frontend has its own flow boundary: `frontend/src/app/login/page.tsx` starts sign-in, `frontend/src/app/auth/callback/route.ts` handles the auth callback, and `frontend/src/middleware.ts` likely protects routes or redirects unauthenticated users. This is the clearest client-side control-plane in the repo.

9. The frontend also has an `api.ts` helper, which likely centralizes calls to the backend API. That makes the frontend-to-backend path a distinct data flow: UI pages talk through a shared API client rather than calling backend endpoints ad hoc from each page.

10. The frontend and backend are intentionally decoupled. The frontend owns presentation, route protection, and auth session handling; the backend owns API validation, business services, and integration logic. Supabase sits across both as the common identity/data service.

11. Testing and delivery are lightweight but present: `backend/test_api_endpoints.py` covers API endpoints, `.github/workflows/ci.yml` defines CI, and `.pre-commit-config.yaml` plus the repo’s branching/PR docs enforce contribution hygiene. These are supporting quality gates, not runtime components.

12. For an architecture diagram, the main boxes should be: browser/client, Next.js frontend, FastAPI backend, Supabase, and email/external notifications. The key arrows are auth/session flow through Supabase, UI/API calls from Next.js to FastAPI, and backend-to-external-service calls for persistence and email.

Main entry points: [`frontend/src/app/login/page.tsx`](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/login/page.tsx) (Auth flow), [`backend/app/services/application_service.py`](https://github.com/deepak4124/campus-admin/blob/main/backend/app/services/application_service.py) (Domain services), [`backend/app/routes/application.py`](https://github.com/deepak4124/campus-admin/blob/main/backend/app/routes/application.py) (HTTP routes), [`frontend/src/app/api.ts`](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>user client"))
end

subgraph group_frontend["Next.js frontend"]
  node_fe_shell["App shell<br/>next.js layout<br/>[layout.tsx]"]
  node_fe_auth["Auth flow<br/>next.js auth<br/>[page.tsx]"]
  node_fe_api["API client<br/>frontend http client<br/>[api.ts]"]
  node_fe_dashboard["Workspace pages<br/>app pages<br/>[page.tsx]"]
end

subgraph group_backend["FastAPI backend"]
  node_be_entry["API entry<br/>fastapi app<br/>[main.py]"]
  node_be_routes["HTTP routes<br/>api routes<br/>[application.py]"]
  node_be_services["Domain services<br/>service layer"]
  node_be_schemas["Data models<br/>pydantic schemas<br/>[application.py]"]
  node_be_core["Core infra<br/>shared infra<br/>[auth.py]"]
end

subgraph group_external["External services"]
  node_supabase[("Supabase<br/>identity/storage")]
  node_email["Email service<br/>notification integration<br/>[email_service.py]"]
end

subgraph group_quality["Quality gates"]
  node_backend_tests["API tests<br/>integration tests"]
  node_ci["CI pipeline<br/>github actions<br/>[ci.yml]"]
end

node_browser -->|"sign in"| node_fe_auth
node_browser -->|"use app"| node_fe_dashboard
node_fe_shell -->|"renders"| node_fe_dashboard
node_fe_auth -->|"sessions"| node_supabase
node_fe_api -->|"api calls"| node_be_entry
node_fe_dashboard -->|"requests"| node_fe_api
node_fe_auth -->|"post-login"| node_fe_api
node_be_entry -->|"routes"| node_be_routes
node_be_routes -->|"delegates"| node_be_services
node_be_services -->|"validates"| node_be_schemas
node_be_services -->|"uses"| node_be_core
node_be_core -->|"auth/storage"| node_supabase
node_be_services -->|"notify"| node_email
node_be_routes -.->|"covered by"| node_backend_tests
node_backend_tests -.->|"runs in"| node_ci
node_fe_auth -.->|"callback state"| node_be_entry

click node_fe_shell "https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/layout.tsx"
click node_fe_auth "https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/login/page.tsx"
click node_fe_api "https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/api.ts"
click node_fe_dashboard "https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/dashboard/page.tsx"
click node_be_entry "https://github.com/deepak4124/campus-admin/blob/main/backend/app/main.py"
click node_be_routes "https://github.com/deepak4124/campus-admin/blob/main/backend/app/routes/application.py"
click node_be_services "https://github.com/deepak4124/campus-admin/blob/main/backend/app/services/application_service.py"
click node_be_schemas "https://github.com/deepak4124/campus-admin/blob/main/backend/app/schemas/application.py"
click node_be_core "https://github.com/deepak4124/campus-admin/blob/main/backend/app/core/auth.py"
click node_email "https://github.com/deepak4124/campus-admin/blob/main/backend/app/services/email_service.py"
click node_backend_tests "https://github.com/deepak4124/campus-admin/blob/main/backend/test_api_endpoints.py"
click node_ci "https://github.com/deepak4124/campus-admin/blob/main/.github/workflows/ci.yml"

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_browser toneBlue
class node_fe_shell,node_fe_auth,node_fe_api,node_fe_dashboard toneAmber
class node_be_entry,node_be_routes,node_be_services,node_be_schemas,node_be_core toneMint
class node_supabase,node_email toneRose
class node_backend_tests,node_ci toneIndigo
```

## Components

### Client

Browser-facing entrypoints and user interaction layer.

- **Browser**: user client · End-user interaction surface for the campus admin app.

### Next.js frontend

App Router UI, auth flow, and API client.

- [App shell](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/layout.tsx): next.js layout · Shared frontend layout, global styles, and app framing. · `frontend/src/app/layout.tsx`
- [Auth flow](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/login/page.tsx): next.js auth · Login page, callback handler, and middleware route control. · `frontend/src/app/login/page.tsx`
- [API client](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/api.ts): frontend http client · Shared client-side helper for calling the backend API. · `frontend/src/app/api.ts`
- [Workspace pages](https://github.com/deepak4124/campus-admin/blob/main/frontend/src/app/dashboard/page.tsx): app pages · Primary user-facing pages for students, faculty, attendance, fees, and reports. · `frontend/src/app/dashboard/page.tsx`

### FastAPI backend

HTTP API, domain services, and shared infrastructure.

- [API entry](https://github.com/deepak4124/campus-admin/blob/main/backend/app/main.py): fastapi app · FastAPI application entrypoint and runtime bootstrap. · `backend/app/main.py`
- [HTTP routes](https://github.com/deepak4124/campus-admin/blob/main/backend/app/routes/application.py): api routes · Endpoint layer exposing application, attendance, directory, and receipt APIs. · `backend/app/routes/application.py`
- [Domain services](https://github.com/deepak4124/campus-admin/blob/main/backend/app/services/application_service.py): service layer · Business operations for application, attendance, directory, receipt, and email flows. · `backend/app/services/application_service.py`
- [Data models](https://github.com/deepak4124/campus-admin/blob/main/backend/app/schemas/application.py): pydantic schemas · Request and response contracts for backend API modules. · `backend/app/schemas/application.py`
- [Core infra](https://github.com/deepak4124/campus-admin/blob/main/backend/app/core/auth.py): shared infra · Authentication and Supabase wiring shared across backend modules. · `backend/app/core/auth.py`

### External services

Supabase and outbound notification dependencies.

- **Supabase**: identity/storage · Common auth and storage backend used by both frontend and backend.
- [Email service](https://github.com/deepak4124/campus-admin/blob/main/backend/app/services/email_service.py): notification integration · Outbound email boundary used by backend services. · `backend/app/services/email_service.py`

### Quality gates

Tests and CI supporting the scaffold.

- [API tests](https://github.com/deepak4124/campus-admin/blob/main/backend/test_api_endpoints.py): integration tests · Backend endpoint coverage for the FastAPI service. · `backend/test_api_endpoints.py`
- [CI pipeline](https://github.com/deepak4124/campus-admin/blob/main/.github/workflows/ci.yml): github actions · Repository automation for continuous integration. · `.github/workflows/ci.yml`

## Connections

- Browser → Auth flow: sign in · Users authenticate through the frontend auth flow.
- Browser → Workspace pages: use app · Users interact with the main pages and workflows.
- App shell → Workspace pages: renders · Shared shell frames the application pages.
- Auth flow → Supabase: sessions · Frontend auth flow exchanges credentials and session state with Supabase.
- API client → API entry: api calls · Frontend centralizes backend requests through one HTTP client.
- Workspace pages → API client: requests · Pages call the shared API client for data and actions.
- Auth flow → API client: post-login · Authenticated frontend state enables API usage.
- API entry → HTTP routes: routes · FastAPI entrypoint mounts the HTTP route layer.
- HTTP routes → Domain services: delegates · Endpoints hand off domain work to services.
- Domain services → Data models: validates · Services operate around structured request and response models.
- Domain services → Core infra: uses · Business logic relies on shared auth and infrastructure wiring.
- Core infra → Supabase: auth/storage · Backend integrates with Supabase for identity and data services.
- Domain services → Email service: notify · Domain workflows can trigger outbound email notifications.
- HTTP routes → API tests: covered by · Endpoint layer is exercised by API tests.
- API tests → CI pipeline: runs in · Tests are executed by the repository CI pipeline.
- Auth flow → API entry: callback state · Login flow ultimately aligns frontend session state with backend-protected APIs.