How rusiththarindu/passgo-fe works
Project Type and Purpose
• This is a front-end web application (“passgo-fe”) built with Next.js 14, TypeScript, and Tailwind CSS.
• It serves as the user interface for a Passport Application Management System called PassGo, handling applicant workflows, admin dashboards, and integrating with a backend API.
File Structure
• Top-level config files (.eslintrc, tsconfig.json, tailwind.config.ts).
• public/ holds static assets (images, PDFs).
• src/app/ contains Next.js App-Router pages, split by route segments:
• /admin → admin dashboard, applications, appointments, renewals
• /applicant → applicant home, profile, passport apply wizard, appointments, support
• /api → server-side API route handlers (e.g., /api/signup/send, /api/appointment/send)
• /login, /signup, /page.tsx, global layouts
• src/components/ hosts UI building blocks: atoms (ui/), molecules (forms, landing sections), organisms (LandingPage, ApplicantDashboard), cards, modals, emails.
• src/api/ organizes API client wrappers and endpoints for admin/applicant/common.
• src/hooks/ custom React hooks layered atop React Query.
• src/contexts/, src/providers/ implement React Contexts (AuthContext, Providers).
• src/store/ Zustand stores for auth and user data.
• src/utils/ helpers, axios wrapper, authentication utilities, validation schemas.
• src/config/ and src/constants/ for theming and constant definitions.
• src/types/ TypeScript interfaces for API payloads, forms, domain objects.
Key Insights from README
• Front-end app communicates with a backend API at NEXT_PUBLIC_API_URL.
• Uses React Query for server-state, Zustand for client-state.
• Auth via JWT, protected routes, role-based access.
• Email notifications and file uploads handled on the backend via Nodemailer and multipart forms.
Main Components
a. User’s Browser – Sends requests, renders React UI
b. Next.js Application
• App Router (server-side rendering, server components)
• Client Components (hydrated React hooks, state management)
• API Routes under src/app/api/* (proxy endpoints for signup & appointment emails)
• Static Asset Server (serving /public)
c. API Client Layer (src/api/*) – abstractions over fetch/Axios, holds endpoints & query keys
d. State Management
• React Query for remote data (applicant data, applications, appointments)
• Zustand for local/user state (auth tokens, user profile)
• React Context for theme, toast provider, auth context
e. UI Layer
• Shadcn UI components, Tailwind styling
• Atomic components (UI primitives), Molecules (forms, cards), Organisms (dashboards, landing page)
f. External Services
• Backend API (Passport API, user management, document storage)
• Email Service (via Nodemailer on backend)
• Third-Party Storage/DB (e.g., S3, Mongo/Postgres) _– implicit in README_
Component Relationships and Interactions
• Browser ↔ Next.js App:
• Initial page load uses SSR/SSG defined by App Router.
• Client components hydrate and call React Query/Zustand hooks.
• Next.js App → Backend API:
• Data fetching via API client wrappers (src/api/*).
• Authenticated requests include JWT in headers or cookies.
• API Routes (server-side):
• Expose endpoints for sending signup and appointment emails (/api/signup/send, /api/appointment/send).
• Use Nodemailer and environment variables.
• State Stores feed UI:
• React Query caches remote data; Zustand holds auth tokens & profile.
• UI Events trigger:
• Form submissions → API client → Backend → DB → Email → React Query invalidation.
Architectural Patterns and Principles
• Separation of Concerns: UI vs. data-fetch logic vs. state management vs. API definitions.
• App Router & Server Components for optimized SSR/CSR balance.
• Layered API Abstraction: Endpoints, API client, React Query hooks.
• Atomic Design in component library.
• Provider Pattern: Toasts, Theme, Auth contexts at root layout.
• Type Safety with TypeScript & Zod schemas for form validation.