Project Structure
The application follows Next.js 15 App Router conventions with a feature-based organization for frontend code.
Top-Level Structure
├── src/
│ ├── app/ # Next.js App Router (pages, layouts, API routes)
│ ├── components/ # Shared UI components
│ ├── features/ # Feature modules (domain-specific logic)
│ ├── helpers/ # Backend utility functions
│ ├── hooks/ # Shared React hooks
│ ├── models/ # Mongoose schema definitions
│ ├── lib/ # Library utilities
│ ├── utils/ # Frontend utilities
│ ├── context/ # React context providers
│ ├── styling/ # Global CSS
│ └── middleware.ts # Route protection middleware
├── public/ # Static assets
├── lib/ # Root-level library config (Firebase)
├── next.config.ts # Next.js configuration
├── tailwind.config.ts # Tailwind CSS configuration
├── vercel.json # Vercel deployment configuration
└── package.json
src/app/ — Routes and Pages
The App Router directory structure maps directly to URL routes:
src/app/
├── layout.tsx # Root layout (fonts, metadata, global providers)
├── page.tsx # Landing page (redirected to /login by middleware)
├── globals.css # Global styles
├── not-found.js # 404 page
├── login/
│ ├── page.tsx # Login page with email/password form
│ └── actions.ts # Server action: login, logout, session creation
├── onboarding/
│ └── page.tsx # New user onboarding (profile, signature, password)
├── dashboard/
│ ├── layout.jsx # Dashboard layout (sidebar wrapper)
│ ├── admin/
│ │ ├── page.tsx # User management
│ │ ├── analytics/ # Analytics dashboard
│ │ └── year_review/ # Year-end review pages
│ ├── main/
│ │ ├── allMoc/
│ │ │ ├── page.tsx # MOC tracking (card view)
│ │ │ └── table/
│ │ │ └── page.tsx # MOC archive (table view)
│ │ └── allPcr/
│ │ └── page.tsx # PCR tracking
│ ├── Moc/
│ │ ├── create/
│ │ │ └── page.tsx # Initiate MOC
│ │ └── list/
│ │ └── [moc_id]/
│ │ └── page.tsx # MOC detail/editing page
│ ├── pcr/
│ │ └── create/
│ │ └── page.tsx # Initiate PCR
│ └── notifications/
│ └── page.tsx # Notification center
└── api/ # API route handlers (see API Reference)
src/components/ — Shared Components
Reusable UI components used across multiple features:
src/components/
├── app-sidebar.tsx # Main navigation sidebar
├── nav-main.tsx # Collapsible sidebar menu renderer
├── nav-user.tsx # User profile section in sidebar
├── team-switcher.tsx # Team/org switcher
├── forms/
│ ├── mocForms/ # MOC-specific form components
│ │ ├── originatorForm.tsx # Part A creation form
│ │ ├── originatorFormPreview.tsx # Part A preview/edit in detail page
│ │ ├── implementer.tsx # Implementer form variant
│ │ └── implementerPreview.tsx # Implementer preview variant
│ ├── formComponents/ # Form field components
│ │ ├── BooleanTablePcr.tsx # Core table-based form renderer
│ │ ├── implementerFormTable.tsx # Part B form definition
│ │ ├── hseqForm.tsx # Part C form definition
│ │ ├── approver.tsx # Part D form definition
│ │ ├── implementation.tsx # Part E form definition
│ │ ├── verification.tsx # Part F form definition
│ │ ├── richTextEditor.tsx # TipTap rich text editor
│ │ ├── datePicker.tsx # Date picker component
│ │ ├── multiSelect.tsx # Multi-select dropdown
│ │ └── select.tsx # Single select dropdown
│ └── addUser.tsx # User creation form (admin)
├── impactAssessment/
│ ├── impactDisplay.tsx # Hazard category checkbox grid
│ ├── topBarImpact.tsx # Impact assessment toolbar
│ └── data.ts # Predefined hazard categories
├── display components/
│ ├── userDisplay.tsx # User avatar/badge/card component
│ ├── displaySection.tsx # Section wrapper with sticky header
│ ├── homePage.tsx # Dashboard home page
│ └── mocDisaplays.tsx # MOC originator display card
└── ui/ # shadcn/ui primitives
src/features/ — Feature Modules
Each feature follows a consistent internal structure:
src/features/{feature-name}/
├── components/ # React components specific to this feature
├── hooks/ # Custom hooks for data fetching and state
├── apis/ # Server actions and API call functions
└── utils/ # Helper functions and type definitions
Key feature modules:
| Module | Path | Purpose |
|---|---|---|
| mocTable | src/features/mocTable/ | MOC and PCR archive table views |
| mocTracking | src/features/mocTracking/ | MOC tracking card components |
| allPcr | src/features/allPcr/ | PCR tracking and display |
| pcrForms | src/features/pcrForms/ | PCR initiation form |
| notification_system | src/features/notification_system/ | In-app notification center |
| onboarding | src/features/onboarding/ | New user onboarding wizard |
| analytics | src/features/analytics/ | Analytics dashboard with charts |
| year_end_review | src/features/year_end_review/ | Year-end HSEQ review document builder |
| moc_overview | src/features/moc_overview/ | Personal MOC overview page |
| shared | src/features/shared/ | Shared components, hooks, and utilities |
| chatFloatingBox | src/features/chatFloatingBox/ | Floating chat component for MOC collaboration |
| print moc | src/features/print moc/ | MOC print/PDF generation |
| pcrPrintOut | src/features/pcrPrintOut/ | PCR print/PDF generation |
src/models/ — Database Schemas
All Mongoose model definitions. See Data Models for details.
src/helpers/ — Backend Utilities
Server-side helper functions used by API routes:
| File | Purpose |
|---|---|
auth.ts | JWT payload extraction from session cookies |
dbConnection.ts | MongoDB connection singleton |
send_email.ts | Email dispatch via AWS Lambda |
pcr_email_helpers.ts | PCR-specific email templates and workflows |
backendFunctions.js | S3 image upload, localStorage utilities |
sendNotification.tsx | In-app notification creation |
dateConversions.tsx | Date formatting utilities |
src/app/api/ — API Routes
All backend API endpoints are in src/app/api/. Each route is a directory containing a route.ts or route.tsx file with exported HTTP method handlers. See the API Reference section for complete documentation.