How alexdataplumbers-labs/hrdocsapp works
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