# rusiththarindu/passgo-fe architecture

> Architecture diagram of the GitHub repository rusiththarindu/passgo-fe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rusiththarindu/passgo-fe
- Repository: https://github.com/rusiththarindu/passgo-fe

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Browser["User's Browser"]:::external

    %% Next.js Application Layer
    subgraph "Next.js Application"
        subgraph "App Router"
            AdminPages["Admin Pages"]:::frontend
            ApplicantPages["Applicant Pages"]:::frontend
            AuthLogin["Login Page"]:::frontend
            AuthSignup["Signup Page"]:::frontend
            GlobalLayout["Global Layout & Styles"]:::frontend
        end
        ClientComp["Client Components"]:::frontend
        subgraph "Serverless API Routes"
            APISignup["/api/signup/send"]:::api
            APIAppointment["/api/appointment/send"]:::api
        end
        StaticAssets["Static Asset Server"]:::frontend
    end

    %% API & State Layers
    APIClient["API Client Layer"]:::api
    StateRemote["React Query Hooks"]:::state
    StateLocal["Zustand Stores"]:::state
    Context["React Contexts"]:::state

    %% UI Component Library
    subgraph "UI Components"
        Atoms["UI Primitives (Atoms)"]:::ui
        Molecules["Molecules"]:::ui
        Organisms["Organisms"]:::ui
        Modals["Modals & Alerts"]:::ui
        Emails["Email Templates"]:::ui
    end

    %% Configuration & Utilities
    subgraph "Config & Types"
        Config["Config & Constants"]:::config
        Utils["Utilities & Helpers"]:::config
        Types["Type Definitions"]:::config
        NextTailwind["tailwind.config.ts\nnext.config.ts"]:::config
    end

    %% External Services
    subgraph "External Services"
        BackendAPI["Backend API"]:::external
        EmailService["Email Service"]:::external
        Database["Database / Storage"]:::external
    end

    %% Data Flows
    Browser -->|HTTP Request| AdminPages
    Browser -->|HTTP Request| ApplicantPages
    Browser -->|HTTP Request| AuthLogin
    Browser -->|HTTP Request| AuthSignup
    Browser -->|Loads CSS/JS| GlobalLayout
    Browser -->|Hydrate| ClientComp

    ClientComp -->|renders| Atoms
    ClientComp -->|renders| Molecules
    ClientComp -->|renders| Organisms
    ClientComp -->|opens| Modals
    ClientComp -->|uses| Emails

    ClientComp -->|React Query fetch| StateRemote
    ClientComp -->|reads/writes| StateLocal
    ClientComp -->|context| Context

    StateRemote -->|calls| APIClient
    APIClient -->|HTTP JSON + JWT| BackendAPI
    APIClient -->|fetch| APISignup
    APIClient -->|fetch| APIAppointment

    APISignup -->|send email via| EmailService
    APIAppointment -->|send email via| EmailService

    BackendAPI -->|read/write| Database

    %% Configuration usage
    Config --> AdminPages
    Config --> ApplicantPages
    Utils --> APIClient
    Utils --> APISignup
    Types --> APIClient
    NextTailwind --> GlobalLayout

    %% Click Events
    click AdminPages "https://github.com/rusiththarindu/passgo-fe/tree/main/src/app/admin"
    click ApplicantPages "https://github.com/rusiththarindu/passgo-fe/tree/main/src/app/applicant"
    click AuthLogin "https://github.com/rusiththarindu/passgo-fe/tree/main/src/app/login"
    click AuthSignup "https://github.com/rusiththarindu/passgo-fe/tree/main/src/app/signup"
    click GlobalLayout "https://github.com/rusiththarindu/passgo-fe/blob/main/src/app/layout.tsx"
    click GlobalLayout "https://github.com/rusiththarindu/passgo-fe/blob/main/src/app/globals.css"
    click APISignup "https://github.com/rusiththarindu/passgo-fe/blob/main/src/app/api/signup/send/route.ts"
    click APIAppointment "https://github.com/rusiththarindu/passgo-fe/blob/main/src/app/api/appointment/send/route.ts"
    click StaticAssets "https://github.com/rusiththarindu/passgo-fe/tree/main/public/"
    click APIClient "https://github.com/rusiththarindu/passgo-fe/tree/main/src/api"
    click StateRemote "https://github.com/rusiththarindu/passgo-fe/tree/main/src/hooks"
    click StateLocal "https://github.com/rusiththarindu/passgo-fe/tree/main/src/store"
    click Context "https://github.com/rusiththarindu/passgo-fe/blob/main/src/contexts/AuthContext.tsx"
    click Context "https://github.com/rusiththarindu/passgo-fe/blob/main/src/providers/Providers.tsx"
    click Atoms "https://github.com/rusiththarindu/passgo-fe/tree/main/src/components/ui"
    click Molecules "https://github.com/rusiththarindu/passgo-fe/tree/main/src/components/molecules"
    click Organisms "https://github.com/rusiththarindu/passgo-fe/tree/main/src/components/organisms"
    click Modals "https://github.com/rusiththarindu/passgo-fe/tree/main/src/components/modals"
    click Modals "https://github.com/rusiththarindu/passgo-fe/blob/main/src/components/ui/toast.tsx"
    click Modals "https://github.com/rusiththarindu/passgo-fe/blob/main/src/components/ui/toaster.tsx"
    click Emails "https://github.com/rusiththarindu/passgo-fe/tree/main/src/components/emails"
    click Config "https://github.com/rusiththarindu/passgo-fe/tree/main/src/config"
    click Config "https://github.com/rusiththarindu/passgo-fe/tree/main/src/constants"
    click Utils "https://github.com/rusiththarindu/passgo-fe/tree/main/src/utils"
    click Utils "https://github.com/rusiththarindu/passgo-fe/blob/main/src/lib/utils.ts"
    click Types "https://github.com/rusiththarindu/passgo-fe/tree/main/src/types"
    click NextTailwind "https://github.com/rusiththarindu/passgo-fe/blob/main/tailwind.config.ts"
    click NextTailwind "https://github.com/rusiththarindu/passgo-fe/blob/main/next.config.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#FFE0B2,stroke:#FF9800,color:#E65100;
    classDef state fill:#E8F5E9,stroke:#43A047,color:#2E7D32;
    classDef ui fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef config fill:#FCE4EC,stroke:#EC407A,color:#880E4F;
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
```
