# alexdataplumbers-labs/hrdocsapp architecture

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

- Interactive diagram: https://gitdiagram.com/alexdataplumbers-labs/hrdocsapp
- Repository: https://github.com/alexdataplumbers-labs/hrdocsapp

## Overview

##### Project Type and Purpose
- This is a full-stack HR documentation and e-signing platform.
- Frontend: Next.js + TypeScript (Tailwind + Shadcn UI), running on Vercel.
- Backend: Node.js/Express + TypeScript, running on Railway.
- Database/Auth/Storage: Supabase (PostgreSQL).
- Core features: form creation, workflow, document generation (PDF), in-app e-signing (Dropbox Sign / HelloSign), notifications, audit logging.

##### File Structure Analysis
- Top-level:
· frontend/ (Next.js app)
· backend/ (Express API)
· supabase/ (DB schema + migrations + config)
· scripts/ (utility scripts)
· docs/ + Guidelines/ + AGENTS.md (process and best practices)
- Frontend patterns:
· src/app (Next.js App Router) with subfolders for auth, admin, fill workflows
· components, hooks, lib/api clients, providers → separation of UI, state, API logic
· e2e, jest, ESLint → testing & linting configuration
- Backend patterns:
· src/routes (Express route handlers)
· src/services (business logic, document generation, template management, notifications)
· src/lib (Supabase client wrapper, validation)
· src/middleware (auth)
· src/jobs (background tasks, documentGenerator)
· src/scripts/test-form-request.ts (dev helpers)
· Configuration: jest.config.js, tsconfig.json, .env.example
- Supabase:
· config.toml, migrations & seed.sql define schema evolution
· Supabase functions for RPC (form_generation)

##### Key Components
- Frontend (Next.js)
· Presentation layer: pages (auth, admin, form fill)
· UI Components (Shadcn/Tailwind)
· API Client (REST calls to backend)
· Supabase Client (Auth, real-time events)
- Backend (Express)
· REST API Endpoints (documents, forms, templates, requests, webhooks)
· Business Services (schema/form/template generation, notification, e-sign integration)
· Background Jobs (documentGenerator)
· Middleware (authentication, validation)
· Supabase SDK for DB operations, Storage, Auth management
- Database (Supabase/PostgreSQL)
· Tables: users, forms, templates, form_requests, notifications, approvals, document_metadata
· Storage buckets for template files & generated PDFs
· Auth subsystem (Supabase Auth)
· RPC & Functions for server-side form generation
- External Services
· Dropbox Sign / HelloSign (e-sign SDK & webhooks)
· Email/SMS provider (notificationService)
- Hosting & Dev Infrastructure
· Vercel (frontend)
· Railway (backend)
· Docker + Supabase CLI (local dev)
· CI/CD (GitHub workflows via .github/ISSUE_TEMPLATE)

##### Relationships & Data Flows
- User (browser) ↔ Next.js frontend (SSR/CSR routes)
- Frontend → Backend REST API (JSON over HTTPS)
- Backend ↔ Supabase (PG queries, Auth admin, Storage)
- Backend → External e-sign service (SDK & webhook callbacks)
- Backend jobs → Supabase functions → Storage (PDFs)
- Supabase real-time events → Frontend (via supabase client) for in-app notifications
- Admin user → Visual form builder → Template stored in Supabase Storage + metadata table
- End user → form fill → form_request row created → triggers document generation

##### Architectural Patterns & Principles
- Separation of concerns: UI vs API vs data access vs business logic vs background jobs
- Modular services: each feature in its own service module (templateService, schemaService)
- Clean folder structure mirroring feature areas
- Event-driven tasks: background jobs trigger on DB/events for PDF generation
- Idempotent migrations (supabase/migrations) and seed data
- Secure by default: middleware for auth, typed schemas for validation

- Frontend on left: subdivide into “App Router” and “UI Components”
- Backend in center: group Routes → Middleware → Services → Jobs
· Browser → Frontend (HTTP)
· Frontend → Backend (REST)
· Backend → Supabase (SDK calls)
· Supabase → Backend (real-time triggers)
· Backend → E-sign (SDK/webhook)
· Backend Jobs → Supabase RPC → Storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend [Vercel]" 
        direction TB
        AppRouter["Next.js App Router"]:::frontend
        UIComp["UI Components (Shadcn/Tailwind)"]:::frontend
        NotificationCenter["NotificationCenter.tsx"]:::frontend
        RESTClient["API Client (REST)"]:::frontend
        SupaClient["Supabase Client"]:::frontend
        UseAuth["useAuth.ts"]:::frontend
        UseUserRole["useUserRole.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend [Railway]"
        direction TB
        Entry["main.ts"]:::backend
        subgraph "Routes"
            direction TB
            Documents["documents.ts"]:::backend
            Forms["forms.ts"]:::backend
            Requests["requests.ts"]:::backend
            Templates["templates.ts"]:::backend
            Webhooks["webhooks.ts"]:::backend
            Health["health.ts"]:::backend
        end
        Middleware["auth.ts"]:::backend
        subgraph "Services"
            direction TB
            FormGen["formGenerationService.ts"]:::service
            SchemaGen["schemaGenerationService.ts"]:::service
            TemplateSvc["templateService.ts"]:::service
            ESignSvc["dropboxSignService.ts"]:::service
            NotifSvc["notificationService.ts"]:::service
            FieldInf["fieldTypeInference.ts"]:::service
        end
        Job["documentGenerator.ts"]:::job
        subgraph "Lib"
            direction TB
            SupaWrapper["supabase.ts"]:::backend
            Validation["validation.ts"]:::backend
        end
        DevScript["test-form-request.ts"]:::backend
    end

    %% Data Layer
    subgraph "Supabase (PostgreSQL)" 
        direction TB
        Tables["Tables: users, forms, templates,..."]:::data
        Storage["Storage Buckets"]:::data
        AuthSub["Auth Subsystem"]:::data
        Functions["RPC & Functions"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ESign["Dropbox Sign / HelloSign"]:::external
        EmailSMS["Email/SMS Provider"]:::external
    end

    %% Connections
    User -->|"visits"| AppRouter
    AppRouter --> UIComp
    AppRouter --> NotificationCenter
    AppRouter --> RESTClient
    AppRouter --> SupaClient
    AppRouter --> UseAuth
    AppRouter --> UseUserRole

    RESTClient -->|"POST /api/*"| Entry
    SupaClient -->|"Realtime & Auth"| AuthSub

    Entry --> Documents
    Entry --> Forms
    Entry --> Requests
    Entry --> Templates
    Entry --> Webhooks
    Entry --> Health

    Documents --> Middleware
    Forms --> Middleware
    Requests --> Middleware
    Templates --> Middleware
    Webhooks --> Middleware

    Middleware --> FormGen
    Middleware --> SchemaGen
    Middleware --> TemplateSvc
    Middleware --> ESignSvc
    Middleware --> NotifSvc
    Middleware --> FieldInf

    FormGen --> SupaWrapper
    SchemaGen --> SupaWrapper
    TemplateSvc --> SupaWrapper
    ESignSvc --> SupaWrapper
    NotifSvc --> SupaWrapper
    FieldInf --> SupaWrapper

    SupaWrapper --> Tables
    SupaWrapper --> Storage
    SupaWrapper --> AuthSub

    Tables --> Job
    Job -->|"RPC form_generation"| Functions
    Functions --> Storage

    ESignSvc --> ESign
    ESign --> Webhooks
    NotifSvc --> EmailSMS

    %% Click Events
    click AppRouter "https://github.com/alexdataplumbers-labs/hrdocsapp/tree/main/frontend/src/app"
    click UIComp "https://github.com/alexdataplumbers-labs/hrdocsapp/tree/main/frontend/src/components"
    click RESTClient "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/frontend/src/lib/api/client.ts"
    click SupaClient "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/frontend/src/lib/supabase/client.ts"
    click UseAuth "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/frontend/src/hooks/useAuth.ts"
    click UseUserRole "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/frontend/src/hooks/useUserRole.ts"

    click Entry "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/main.ts"
    click Documents "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/documents.ts"
    click Forms "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/forms.ts"
    click Requests "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/requests.ts"
    click Templates "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/templates.ts"
    click Webhooks "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/webhooks.ts"
    click Health "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/routes/health.ts"

    click FormGen "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/formGenerationService.ts"
    click SchemaGen "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/schemaGenerationService.ts"
    click TemplateSvc "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/templateService.ts"
    click ESignSvc "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/dropboxSignService.ts"
    click NotifSvc "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/notificationService.ts"
    click FieldInf "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/services/fieldTypeInference.ts"

    click Job "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/jobs/documentGenerator.ts"
    click Middleware "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/middleware/auth.ts"
    click SupaWrapper "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/lib/supabase.ts"
    click Validation "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/lib/validation.ts"
    click DevScript "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/backend/src/scripts/test-form-request.ts"
    click NotificationCenter "https://github.com/alexdataplumbers-labs/hrdocsapp/blob/main/frontend/src/components/layout/NotificationCenter.tsx"

    %% Styles
    classDef frontend fill:#E0F2FE,stroke:#0284C7,color:#0369A1
    classDef backend fill:#ECFDF5,stroke:#16A34A,color:#166534
    classDef service fill:#D1FAE5,stroke:#10B981,color:#047857
    classDef job fill:#F0FDF4,stroke:#65A30D,color:#4D7C0F
    classDef data fill:#FFFAEB,stroke:#F59E0B,color:#92400E
    classDef external fill:#F3F4F6,stroke:#6B7280,color:#374151
    classDef user fill:#FFFFFF,stroke:#000000,color:#000000,stroke-width:2px
```
