How deepak4124/campus-admin works
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: page.tsx Auth flow · application_service.py Domain services · application.py HTTP routes · api.ts API client
Components 14
Client
Browser-facing entrypoints and user interaction layer.
- Browser · End-user interaction surface for the campus admin app.
Next.js frontend
App Router UI, auth flow, and API client.
- App shell · Shared frontend layout, global styles, and app framing.
frontend/src/app/layout.tsx - Auth flow · Login page, callback handler, and middleware route control.
frontend/src/app/login/page.tsx - API client · Shared client-side helper for calling the backend API.
frontend/src/app/api.ts - Workspace 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 · FastAPI application entrypoint and runtime bootstrap.
backend/app/main.py - HTTP routes · Endpoint layer exposing application, attendance, directory, and receipt APIs.
backend/app/routes/application.py - Domain services · Business operations for application, attendance, directory, receipt, and email flows.
backend/app/services/application_service.py - Data models · Request and response contracts for backend API modules.
backend/app/schemas/application.py - Core infra · Authentication and Supabase wiring shared across backend modules.
backend/app/core/auth.py
External services
Supabase and outbound notification dependencies.
- Supabase · Common auth and storage backend used by both frontend and backend.
- Email service · Outbound email boundary used by backend services.
backend/app/services/email_service.py
Quality gates
Tests and CI supporting the scaffold.
- API tests · Backend endpoint coverage for the FastAPI service.
backend/test_api_endpoints.py - CI pipeline · Repository automation for continuous integration.
.github/workflows/ci.yml
Connections 16
- 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.