How abhijithd194/admission-management-crm works
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: App.tsx App Shell · index.ts App Router · src/trpc.ts tRPC Client · src/trpc.ts tRPC Core
Components 28
Client
React/Vite browser application
- Browser UI · Authenticated single-page app entrypoint
client/src/main.tsx - App Shell · Top-level client routing and page composition
client/src/App.tsx - Layout · Shared authenticated page chrome
client/src/components/Layout.tsx - Protected Route · Blocks unauthenticated navigation on the client
client/src/components/ProtectedRoute.tsx - Auth Store · Client auth state and role awareness
client/src/store/authStore.ts - tRPC Client · React Query-backed typed client for server procedures
client/src/trpc.ts - Login · Authentication entry screen
client/src/pages/Login.tsx - Dashboard · Operational overview and metrics
client/src/pages/Dashboard.tsx - Masters · Institution and program setup workflow
client/src/pages/Masters.tsx - Quotas · Seat quota configuration workflow
client/src/pages/Quotas.tsx - Applicants · Applicant management and document tracking
client/src/pages/Applicants.tsx - Allocation · Seat allocation workflow
client/src/pages/Allocation.tsx - Admissions · Admission confirmation workflow
client/src/pages/Admissions.tsx - Applicant Detail · Per-applicant status and actions
client/src/pages/ApplicantDetail.tsx - Modal · Reusable create/edit form surface
client/src/components/Modal.tsx
Server
Express and tRPC API backend
- API Entry · Server bootstrap and HTTP mount point
server/src/index.ts - Context · Builds request context from JWT and request data
server/src/context.ts - tRPC Core · tRPC initialization and role guard helpers
server/src/trpc.ts - App Router · Root router composed from domain routers
server/src/routers/index.ts - SQLite DB · Embedded persistence for all domain data
server/src/db.ts - Auth · Login and authentication procedures
server/src/routers/auth.ts - Masters · Master data procedures
server/src/routers/masters.ts - Quotas · Quota validation and persistence procedures
server/src/routers/quotas.ts - Applicants · Applicant record and document procedures
server/src/routers/applicants.ts - Allocation · Seat allocation procedures
server/src/routers/allocation.ts - Admission · Fee-gated admission confirmation procedures
server/src/routers/admission.ts - Dashboard · Derived metrics and operational summaries
server/src/routers/dashboard.ts
Shared
Cross-tier validation and types
- Shared Schemas · Cross-tier validation and inferred types
shared/schemas.ts
Connections 48
- 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