# abhijithd194/admission-management-crm architecture

> Architecture diagram of the GitHub repository abhijithd194/admission-management-crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhijithd194/admission-management-crm
- Repository: https://github.com/abhijithd194/admission-management-crm

## Overview

1. This repository is a two-tier TypeScript application: a React/Vite frontend in `client/` and an Express + tRPC backend in `server/`, with shared Zod schemas in `shared/` to keep request/response validation aligned across both sides.

2. The primary runtime boundary is the browser talking to the server through tRPC. The frontend does not call REST endpoints directly; it uses a typed tRPC client wrapped with React Query, so UI data fetching, mutations, and cache updates are driven by the server router contracts.

3. The backend is organized around a single tRPC app router composed from feature routers in `server/src/routers/`. Each router maps to a domain area: `auth`, `masters`, `quotas`, `applicants`, `allocation`, `admission`, and `dashboard`. This makes the server architecture domain-centric rather than layered by generic controllers/services.

4. Persistence is handled by SQLite via `better-sqlite3` in `server/src/db.ts`. That file is the data foundation for the whole system: master records, applicants, quotas, allocations, admissions, and dashboard aggregates all ultimately derive from this local database.

5. Authentication is JWT-based. `server/src/context.ts` builds request context from the incoming token, and `server/src/trpc.ts` provides role-guard helpers used by routers to enforce access by role. The app distinguishes at least three roles: Admin, Admission Officer, and Management.

6. Authorization is a key architectural boundary. The UI uses `ProtectedRoute` and a Zustand auth store to prevent unauthenticated access and to steer navigation, while the backend remains the source of truth for permission checks and action-level enforcement.

7. The frontend is a multi-page SPA with route-level screens in `client/src/pages/`. The major screens correspond directly to business workflows: Login, Dashboard, Masters setup, Quotas, Applicants, Applicant Detail, Allocation, and Admissions. `Layout.tsx` provides the shared shell for authenticated pages, while `Modal.tsx` supports entity editing/creation workflows.

8. The main business flow is sequential:
   - Admin configures institution/campus/department/program/year masters.
   - Quotas are defined against intake, with validation preventing quota totals from exceeding available seats.
   - Applicants are created and managed with document status tracking.
   - Seats are allocated under government or management flows.
   - Admission is confirmed only after fee payment, which triggers admission number generation.

9. Seat management is enforced in the backend, not just the UI. The README’s rules align with the server design: quota saves are validated, allocation is blocked when full, seat counters are derived from database counts, and admission confirmation is rejected unless the fee status is paid.

10. The dashboard is an aggregation layer rather than a separate data store. `server/src/routers/dashboard.ts` appears to collect derived metrics such as seat fill rates, quota breakdowns, pending documents, and pending fees, which the frontend uses for operational monitoring.

11. Shared validation is a major architectural feature. `shared/schemas.ts` is reused by both client and server to define Zod schemas and inferred types, reducing drift between form inputs, mutation payloads, and database-facing validation.

12. From a deployment perspective, the system is a conventional separated frontend/backend application: Vite serves the client, the Node server serves the API, and the server persists data to a local SQLite file. `render.yaml` suggests the repo is intended to be deployed as a hosted service, but the core architecture remains a browser client plus API server plus embedded database.

Main entry points: [`client/src/App.tsx`](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/App.tsx) (App Shell), [`server/src/routers/index.ts`](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/index.ts) (App Router), [`client/src/trpc.ts`](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/trpc.ts) (tRPC Client), [`server/src/trpc.ts`](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/trpc.ts) (tRPC Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser UI<br/>spa<br/>[main.tsx]"))
  node_app_shell["App Shell<br/>routing/shell<br/>[App.tsx]"]
  node_layout["Layout<br/>shell component<br/>[Layout.tsx]"]
  node_protected_route["Protected Route<br/>auth guard<br/>[ProtectedRoute.tsx]"]
  node_auth_store[("Auth Store<br/>zustand state<br/>[authStore.ts]")]
  node_trpc_client["tRPC Client<br/>typed api client<br/>[trpc.ts]"]
  node_login_page["Login<br/>screen<br/>[Login.tsx]"]
  node_dashboard_page["Dashboard<br/>screen<br/>[Dashboard.tsx]"]
  node_masters_page["Masters<br/>screen<br/>[Masters.tsx]"]
  node_quotas_page["Quotas<br/>screen<br/>[Quotas.tsx]"]
  node_applicants_page["Applicants<br/>screen<br/>[Applicants.tsx]"]
  node_allocation_page["Allocation<br/>screen<br/>[Allocation.tsx]"]
  node_admissions_page["Admissions<br/>screen<br/>[Admissions.tsx]"]
  node_detail_page["Applicant Detail<br/>screen"]
  node_modal["Modal<br/>ui dialog<br/>[Modal.tsx]"]
end

subgraph group_server["Server"]
  node_api_entry(("API Entry<br/>express app<br/>[index.ts]"))
  node_request_context["Context<br/>request auth<br/>[context.ts]"]
  node_trpc_core["tRPC Core<br/>router guards<br/>[trpc.ts]"]
  node_app_router["App Router<br/>router composition<br/>[index.ts]"]
  node_db[("SQLite DB<br/>better-sqlite3 store<br/>[db.ts]")]
  node_auth_router["Auth<br/>domain router<br/>[auth.ts]"]
  node_masters_router["Masters<br/>domain router<br/>[masters.ts]"]
  node_quotas_router["Quotas<br/>domain router<br/>[quotas.ts]"]
  node_applicants_router["Applicants<br/>domain router<br/>[applicants.ts]"]
  node_allocation_router["Allocation<br/>domain router<br/>[allocation.ts]"]
  node_admission_router["Admission<br/>domain router<br/>[admission.ts]"]
  node_dashboard_router["Dashboard<br/>aggregation router<br/>[dashboard.ts]"]
end

subgraph group_shared["Shared"]
  node_shared_schemas["Shared Schemas<br/>zod contract<br/>[schemas.ts]"]
end

node_browser --> node_app_shell
node_app_shell --> node_protected_route
node_app_shell --> node_login_page
node_app_shell --> node_dashboard_page
node_app_shell --> node_masters_page
node_app_shell --> node_quotas_page
node_app_shell --> node_applicants_page
node_app_shell --> node_allocation_page
node_app_shell --> node_admissions_page
node_app_shell --> node_detail_page
node_protected_route --> node_auth_store
node_layout --> node_modal
node_dashboard_page --> node_trpc_client
node_masters_page --> node_trpc_client
node_quotas_page --> node_trpc_client
node_applicants_page --> node_trpc_client
node_allocation_page --> node_trpc_client
node_admissions_page --> node_trpc_client
node_detail_page --> node_trpc_client
node_trpc_client --> node_app_router
node_api_entry --> node_request_context
node_api_entry --> node_app_router
node_request_context --> node_trpc_core
node_app_router --> node_auth_router
node_app_router --> node_masters_router
node_app_router --> node_quotas_router
node_app_router --> node_applicants_router
node_app_router --> node_allocation_router
node_app_router --> node_admission_router
node_app_router --> node_dashboard_router
node_auth_router --> node_trpc_core
node_masters_router --> node_trpc_core
node_quotas_router --> node_trpc_core
node_applicants_router --> node_trpc_core
node_allocation_router --> node_trpc_core
node_admission_router --> node_trpc_core
node_dashboard_router --> node_trpc_core
node_auth_router --> node_db
node_masters_router --> node_db
node_quotas_router --> node_db
node_applicants_router --> node_db
node_allocation_router --> node_db
node_admission_router --> node_db
node_dashboard_router --> node_db
node_auth_router --> node_shared_schemas
node_masters_router --> node_shared_schemas
node_quotas_router --> node_shared_schemas
node_applicants_router --> node_shared_schemas

click node_browser "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/main.tsx"
click node_app_shell "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/App.tsx"
click node_layout "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/Layout.tsx"
click node_protected_route "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/ProtectedRoute.tsx"
click node_auth_store "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/store/authStore.ts"
click node_trpc_client "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/trpc.ts"
click node_login_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Login.tsx"
click node_dashboard_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Dashboard.tsx"
click node_masters_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Masters.tsx"
click node_quotas_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Quotas.tsx"
click node_applicants_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Applicants.tsx"
click node_allocation_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Allocation.tsx"
click node_admissions_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Admissions.tsx"
click node_detail_page "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/ApplicantDetail.tsx"
click node_modal "https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/Modal.tsx"
click node_api_entry "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/index.ts"
click node_request_context "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/context.ts"
click node_trpc_core "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/trpc.ts"
click node_app_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/index.ts"
click node_db "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/db.ts"
click node_auth_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/auth.ts"
click node_masters_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/masters.ts"
click node_quotas_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/quotas.ts"
click node_applicants_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/applicants.ts"
click node_allocation_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/allocation.ts"
click node_admission_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/admission.ts"
click node_dashboard_router "https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/dashboard.ts"
click node_shared_schemas "https://github.com/abhijithd194/admission-management-crm/blob/main/shared/schemas.ts"

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,node_app_shell,node_layout,node_protected_route,node_auth_store,node_trpc_client,node_login_page,node_dashboard_page,node_masters_page,node_quotas_page,node_applicants_page,node_allocation_page,node_admissions_page,node_detail_page,node_modal toneBlue
class node_api_entry,node_request_context,node_trpc_core,node_app_router,node_db,node_auth_router,node_masters_router,node_quotas_router,node_applicants_router,node_allocation_router,node_admission_router,node_dashboard_router toneAmber
class node_shared_schemas toneMint
```

## Components

### Client

React/Vite browser application

- [Browser UI](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/main.tsx): spa · Authenticated single-page app entrypoint · `client/src/main.tsx`
- [App Shell](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/App.tsx): routing/shell · Top-level client routing and page composition · `client/src/App.tsx`
- [Layout](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/Layout.tsx): shell component · Shared authenticated page chrome · `client/src/components/Layout.tsx`
- [Protected Route](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/ProtectedRoute.tsx): auth guard · Blocks unauthenticated navigation on the client · `client/src/components/ProtectedRoute.tsx`
- [Auth Store](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/store/authStore.ts): zustand state · Client auth state and role awareness · `client/src/store/authStore.ts`
- [tRPC Client](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/trpc.ts): typed api client · React Query-backed typed client for server procedures · `client/src/trpc.ts`
- [Login](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Login.tsx): screen · Authentication entry screen · `client/src/pages/Login.tsx`
- [Dashboard](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Dashboard.tsx): screen · Operational overview and metrics · `client/src/pages/Dashboard.tsx`
- [Masters](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Masters.tsx): screen · Institution and program setup workflow · `client/src/pages/Masters.tsx`
- [Quotas](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Quotas.tsx): screen · Seat quota configuration workflow · `client/src/pages/Quotas.tsx`
- [Applicants](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Applicants.tsx): screen · Applicant management and document tracking · `client/src/pages/Applicants.tsx`
- [Allocation](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Allocation.tsx): screen · Seat allocation workflow · `client/src/pages/Allocation.tsx`
- [Admissions](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/Admissions.tsx): screen · Admission confirmation workflow · `client/src/pages/Admissions.tsx`
- [Applicant Detail](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/pages/ApplicantDetail.tsx): screen · Per-applicant status and actions · `client/src/pages/ApplicantDetail.tsx`
- [Modal](https://github.com/abhijithd194/admission-management-crm/blob/main/client/src/components/Modal.tsx): ui dialog · Reusable create/edit form surface · `client/src/components/Modal.tsx`

### Server

Express and tRPC API backend

- [API Entry](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/index.ts): express app · Server bootstrap and HTTP mount point · `server/src/index.ts`
- [Context](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/context.ts): request auth · Builds request context from JWT and request data · `server/src/context.ts`
- [tRPC Core](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/trpc.ts): router guards · tRPC initialization and role guard helpers · `server/src/trpc.ts`
- [App Router](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/index.ts): router composition · Root router composed from domain routers · `server/src/routers/index.ts`
- [SQLite DB](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/db.ts): better-sqlite3 store · Embedded persistence for all domain data · `server/src/db.ts`
- [Auth](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/auth.ts): domain router · Login and authentication procedures · `server/src/routers/auth.ts`
- [Masters](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/masters.ts): domain router · Master data procedures · `server/src/routers/masters.ts`
- [Quotas](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/quotas.ts): domain router · Quota validation and persistence procedures · `server/src/routers/quotas.ts`
- [Applicants](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/applicants.ts): domain router · Applicant record and document procedures · `server/src/routers/applicants.ts`
- [Allocation](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/allocation.ts): domain router · Seat allocation procedures · `server/src/routers/allocation.ts`
- [Admission](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/admission.ts): domain router · Fee-gated admission confirmation procedures · `server/src/routers/admission.ts`
- [Dashboard](https://github.com/abhijithd194/admission-management-crm/blob/main/server/src/routers/dashboard.ts): aggregation router · Derived metrics and operational summaries · `server/src/routers/dashboard.ts`

### Shared

Cross-tier validation and types

- [Shared Schemas](https://github.com/abhijithd194/admission-management-crm/blob/main/shared/schemas.ts): zod contract · Cross-tier validation and inferred types · `shared/schemas.ts`

## Connections

- Browser UI → App Shell: Renders application routes and screens
- App Shell → Protected Route: Wraps authenticated areas
- App Shell → Login: Shows login flow
- App Shell → Dashboard: Navigates to operational screens
- App Shell → Masters: Navigates to setup screens
- App Shell → Quotas: Navigates to quota management
- App Shell → Applicants: Navigates to applicant management
- App Shell → Allocation: Navigates to allocation workflow
- App Shell → Admissions: Navigates to admission workflow
- App Shell → Applicant Detail: Shows applicant detail view
- Protected Route → Auth Store: Checks authenticated role state
- Layout → Modal: Supports create and edit flows
- Dashboard → tRPC Client: Fetches summary metrics
- Masters → tRPC Client: Reads and updates master data
- Quotas → tRPC Client: Validates and saves quotas
- Applicants → tRPC Client: Manages applicants and documents
- Allocation → tRPC Client: Runs allocation actions
- Admissions → tRPC Client: Confirms admissions
- Applicant Detail → tRPC Client: Loads applicant-specific data
- tRPC Client → App Router: Calls typed server procedures
- API Entry → Context: Builds per-request auth context
- API Entry → App Router: Mounts the API router
- Context → tRPC Core: Supplies identity and role data
- App Router → Auth: Composes auth domain
- App Router → Masters: Composes master data domain
- App Router → Quotas: Composes quota domain
- App Router → Applicants: Composes applicant domain
- App Router → Allocation: Composes allocation domain
- App Router → Admission: Composes admission domain
- App Router → Dashboard: Composes dashboard domain
- Auth → tRPC Core: Uses auth and role guards
- Masters → tRPC Core: Uses role-protected procedures
- Quotas → tRPC Core: Uses role-protected procedures
- Applicants → tRPC Core: Uses role-protected procedures
- Allocation → tRPC Core: Uses role-protected procedures
- Admission → tRPC Core: Uses role-protected procedures
- Dashboard → tRPC Core: Uses role-protected procedures
- Auth → SQLite DB: Reads user and session data
- Masters → SQLite DB: Persists master records
- Quotas → SQLite DB: Checks and stores quota data
- Applicants → SQLite DB: Stores applicant records and statuses
- Allocation → SQLite DB: Derives seat counts from persistence
- Admission → SQLite DB: Checks payment and writes admissions
- Dashboard → SQLite DB: Aggregates operational metrics
- Auth → Shared Schemas: Validates auth payloads
- Masters → Shared Schemas: Validates master data payloads
- Quotas → Shared Schemas: Validates quota payloads
- Applicants → Shared Schemas: Validates applicant payloads
