# munuchapterhkn/hkrecruitment architecture

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

- Interactive diagram: https://gitdiagram.com/munuchapterhkn/hkrecruitment
- Repository: https://github.com/munuchapterhkn/hkrecruitment

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (app directory structure) that serves as a recruitment platform for the Mu Nu Chapter of Eta Kappa Nu.
- It provides candidate management (dashboards, candidate details, stage transitions), authentication, database-backed storage, and integrates with Google Drive and an n8n workflow engine.

##### File Structure
- **src/app/**: Next.js “app” routes and pages (frontend + server-side).
- `/api/auth/[...all]/route.ts` – NextAuth (or custom) API for authentication.
- `/dashboard/*` – Protected UI routes for candidate workflows.
- **src/components/** & **src/components/ui/**: Reusable React UI components (modals, buttons, layouts).
- **src/db/**: Drizzle ORM config, schema, seed/reset scripts.
- **src/lib/**: Business-logic layers:
- `/lib/server/auth.ts` – server-side auth utilities
- `/lib/google/drive/*` – Google Drive integration
- `/lib/models/*` – Data access layer wrappers over the ORM
- **n8n/**: JSON workflow definitions (automations).
- **docker-compose.yml**, **initdb.sh**: Local dev containers (Postgres, n8n).
- **drizzle.config.ts**, **pnpm-workspace.yaml**, **next.config.ts**: Configuration and build orchestration.

##### README for Additional Insights
- Confirms Next.js dev flow (`pnpm dev`), internal contributors, GNU GPL v3.
- References docs/README for setup (likely includes DB and n8n container definitions).

a. Main Components
- **Client Browser (React/Next.js)** – UI layer served via SSR/SSG.
- **Next.js Server (Frontend + API)** – Handles page rendering and REST/Route handlers under `/api`.
- **Authentication Service** – NextAuth engine within Next.js, connecting to database/session store + OAuth providers.
- **Database (PostgreSQL)** – stores users, candidates, stages via Drizzle ORM.
- **n8n Workflow Engine** – runs JSON-defined automations (e.g., notifications, data sync).
- **External Services** – Google Drive API for file storage; Email/SMTP; OAuth identity providers.
- **DevOps/Infrastructure** – Docker Compose orchestrating containers; PNPM workspace; CI/CD.

b. Relationships & Data Flow
1. User → Browser UI → Next.js page rendering
2. UI invokes Next.js API routes → Business logic in `src/lib` → Drizzle ORM → PostgreSQL
3. Auth flows: UI redirects to OAuth provider → Next.js Auth API → DB session storage
4. Backend triggers n8n workflows via webhooks or direct HTTP calls
5. n8n connects to Google Drive for file operations (folders/files)
6. n8n can push updates back to the Next.js API or send emails

c. Architectural Patterns & Principles
- **Monorepo with PNPM** – unified dependency management.
- **Modular Frontend** – React components, hooks, contexts for ability-based rendering.
- **Layered Backend** – API routes → server utilities (`lib/server`) → data models → DB.
- **Infrastructure-as-Code** – Docker Compose + init scripts.
- **Workflow-Oriented Services** – n8n handles asynchronous tasks, decoupling them from user requests.

d. Key Technologies & Frameworks
- Next.js (React, SSR/SSG, App Router)
- TypeScript, Drizzle ORM, PostgreSQL
- NextAuth or custom auth handlers
- n8n (workflow engine)
- Google Drive API integration
- Tailwind/PostCSS, ESLint, Prettier, Husky

##### Detail without Overthinking
- Data models and seed/reset scripts as part of the DB layer.
- Docker Compose as the orchestration layer that brings up DB + n8n + Next.js.
- Every node that moves or transforms data: UI → API → ORM → DB → workflows → external.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend Layer"
        Browser["User Browser"]:::frontend
        NextJSUI["Next.js UI (app routes)"]:::frontend
        AbilityContext["AbilityContext (Context)"]:::frontend
        CanComp["Can Component"]:::frontend
        UIComponents["UI Components Library"]:::frontend
    end

    subgraph "Backend Layer"
        API["API Routes (src/app/api)"]:::backend
        AuthAPI["Auth Route ([...all]/route.ts)"]:::backend
        AuthUtils["Auth Utils"]:::backend
        BusinessLogic["Business Logic"]:::backend
        StageMgmt["Stage Management"]:::backend
        ApplicantsModel["Applicants Model"]:::backend
        UsersModel["Users Model"]:::backend
        GoogleDriveInt["Google Drive Integration"]:::backend
    end

    subgraph "Database Layer"
        DrizzleConfig["Drizzle Config"]:::database
        DBIndex["DB Index"]:::database
        Schema["Schema Definitions"]:::database
        AuthSchema["Auth Schema"]:::database
        Seed["Seed Scripts"]:::database
        Reset["Reset Scripts"]:::database
        Postgres["PostgreSQL"]:::database
    end

    subgraph "Workflow Engine"
        N8n["n8n Workflow Engine"]:::workflow
    end

    subgraph "External Services"
        OAuth["OAuth Providers"]:::external
        GoogleDriveAPI["Google Drive API"]:::external
        EmailServ["Email/SMTP Service"]:::external
    end

    subgraph "Infrastructure"
        DockerComp["Docker Compose"]:::infra
        InitDB["Init DB Script"]:::infra
        PNPM["PNPM Workspace"]:::infra
        NextConfig["Next.js Config"]:::infra
    end

    %% Connections
    Browser --> NextJSUI
    NextJSUI --> API
    NextJSUI --> AbilityContext
    NextJSUI --> CanComp
    NextJSUI --> UIComponents

    API --> AuthAPI
    API --> BusinessLogic
    AuthAPI --> AuthUtils
    AuthAPI --> OAuth
    AuthUtils --> AuthSchema
    AuthUtils --> DBIndex

    BusinessLogic --> StageMgmt
    BusinessLogic --> ApplicantsModel
    BusinessLogic --> UsersModel
    StageMgmt --> ApplicantsModel
    StageMgmt --> UsersModel
    BusinessLogic --> GoogleDriveInt
    GoogleDriveInt --> GoogleDriveAPI

    ApplicantsModel --> DBIndex
    UsersModel --> DBIndex
    DBIndex --> Postgres
    Schema --> Postgres
    AuthSchema --> Postgres
    Seed --> Postgres
    Reset --> Postgres

    API --> N8n
    N8n --> GoogleDriveAPI
    N8n --> EmailServ
    N8n --> API

    DockerComp --> NextJSUI
    DockerComp --> API
    DockerComp --> Postgres
    DockerComp --> N8n
    DockerComp --> InitDB
    DockerComp --> PNPM
    DockerComp --> NextConfig

    %% Click Events
    click NextJSUI "https://github.com/munuchapterhkn/hkrecruitment/tree/main/src/app"
    click API "https://github.com/munuchapterhkn/hkrecruitment/tree/main/src/app/api"
    click AuthAPI "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/app/api/auth/[...all]/route.ts"
    click AuthUtils "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/lib/server/auth.ts"
    click UIComponents "https://github.com/munuchapterhkn/hkrecruitment/tree/main/src/components/ui"
    click AbilityContext "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/components/ability/AbilityContext.tsx"
    click CanComp "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/components/ability/Can.tsx"
    click DrizzleConfig "https://github.com/munuchapterhkn/hkrecruitment/blob/main/drizzle.config.ts"
    click DBIndex "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/db/index.ts"
    click Schema "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/db/schema.ts"
    click AuthSchema "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/db/auth-schema.ts"
    click Seed "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/db/seed.ts"
    click Reset "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/db/reset.ts"
    click N8n "https://github.com/munuchapterhkn/hkrecruitment/blob/main/n8n/main.json"
    click GoogleDriveInt "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/lib/google/drive/index.ts"
    click ApplicantsModel "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/lib/models/applicants.ts"
    click UsersModel "https://github.com/munuchapterhkn/hkrecruitment/blob/main/src/lib/models/users.ts"
    click InitDB "https://github.com/munuchapterhkn/hkrecruitment/blob/main/initdb.sh"
    click PNPM "https://github.com/munuchapterhkn/hkrecruitment/blob/main/pnpm-workspace.yaml"
    click NextConfig "https://github.com/munuchapterhkn/hkrecruitment/blob/main/next.config.ts"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D6F5D6,stroke:#28a745,color:#236e24;
    classDef database fill:#FFE5B4,stroke:#e07b00,color:#b45f06;
    classDef workflow fill:#E3D5FF,stroke:#6f42c1,color:#4e2a84;
    classDef external fill:#F0F0F0,stroke:#6c757d,color:#495057;
    classDef infra fill:#E8E8E8,stroke:#343a40,color:#212529;
```
