Skip to main content

Repository Blueprint & Project Structure

This document provides a complete technical map of the veridex-hitech-web-application repository. It inventories root configuration files, public static assets, operations scripts, and the internal modular organization of src/.

1. Root Configuration Files & Manifests​

FilenamePurpose & Key Configurations
package.jsonDefines project metadata, engine constraint (node >= 22.0.0), scripts (dev, build, lint, type-check, format, seed:*), and 36+ dependencies.
next.config.tsNext.js configuration. Enforces output: "standalone", serverExternalPackages: ["geoip-lite"], 8 MB Server Action body limit (bodySizeLimit: "8mb"), asset caching headers, and apex 301 canonical redirects.
tsconfig.jsonTypeScript 5 configuration. Sets strict type-checking, JSX preservation for Next.js, and path alias mapping ("@/*": ["./src/*"]).
DockerfileMulti-stage production container build (Base, Dependencies, Builder, Runner) optimizing Alpine/Debian image size for Azure Web Apps.
.env.exampleDefinitive reference blueprint documenting all required environment variables across development, staging, and production tiers.
tailwind.config.jsTailwind CSS v4 styling rules, design tokens, color ramps, typography plugins, and animation keyframes.
postcss.config.mjsPostCSS pipeline integrating @tailwindcss/postcss with Next.js build steps.
eslint.config.mjsModern Flat ESLint 9 configuration extending next/core-web-vitals with custom TypeScript linting rules.
components.jsonshadcn/ui configuration defining component alias paths, Tailwind CSS variable styling, and icon library (lucide-react).
.nvmrcPins Node.js version to 22 for consistent development and CI/CD runtime environments.

2. Directory Architecture Blueprint​

veridex-hitech-web-application/
├── .github/
│   └── workflows/              # CI/CD workflows for building and deploying to Azure
├── docs/                       # Technical architecture manuals, integration guides, license reports
│   ├── API-ENDPOINTS.md        # Raw REST API endpoint specifications
│   ├── HTI-Lead-Ingestion-API-Guide.md
│   ├── PROJECT-MASTER-CONTEXT.md
│   ├── WIDGET-INTEGRATION-GUIDE.md
│   └── licenses.txt            # Production license compliance audit
├── public/                     # Static assets served from web root
│   ├── figma/                  # High-resolution WebP and SVG UI illustrations
│   ├── lottie/                 # Lottie animation JSON files
│   ├── widget.js               # Standalone embeddable partner widget (Shadow DOM)
│   ├── widget-mark.png         # Branded verified badge asset for widgets
│   ├── widget-test.html        # Local test harness for web widgets
│   ├── robots.txt              # Search engine crawler directives
│   └── favicon.ico             # Site favicon
├── scripts/                    # Automation, database seeding, and testing CLI tools
│   ├── seed-super-admin.ts     # Provisions root super_admin account
│   ├── seed-admins.ts          # Provisions standard test administrator accounts
│   ├── update-admin-credentials.ts # Securely updates administrator passwords
│   ├── generate-licenses.ts    # Audits production dependencies and exports licenses.txt
│   ├── test-rate-limiter.ts    # Verifies sliding-window rate limit enforcement
│   ├── send-test-email.js      # Verifies Azure Email Function and SMTP connectivity
│   └── send-*.ts               # Integration test scripts for quote, contact, claims, calls
├── src/                        # Primary application source code
│   ├── app/                    # Next.js App Router root
│   ├── components/             # Reusable UI primitives and domain features
│   ├── config/                 # Static metadata, route definitions, widget configs
│   ├── i18n/                   # next-intl configuration and routing
│   ├── lib/                    # Core business logic, DB models, utilities, API clients
│   ├── messages/               # Bilingual localization dictionaries (/en, /es)
│   ├── server/actions/         # Next.js Server Actions (mutations & queries)
│   ├── services/               # Shared service layer (SEO, metadata)
│   └── types/                  # Global TypeScript type declarations

3. Deep Source Map: src/ Organization​

3.1 App Router (src/app)​

The App Router handles both UI routing and backend REST API route handlers:

  • src/app/[locale]: Bilingual route group supporting English (/en) and Spanish (/es):
    • (auth): Unauthenticated auth routes: /sign-in, /register, /forgot-password, /reset-password, /set-password.
    • (dashboard): Authenticated customer portal /dashboard (profile, referrals, submissions, draft resumption).
    • admin: Back-office control center (/admin, /admin/meta-leads, /admin/system-health).
    • insurance/[slug]: Dynamic route rendering detail pages for all 20 supported insurance lines.
    • blog & blog/[slug]: Dynamic SEO-optimized blog catalog and reader view.
    • l/: Parallel edge-optimized Lite Web Platform route tree (/l/*) for commercial haulers.
    • e/[slug]: Dynamic field marketing QR event campaign landing pages.
    • embed/widget: Responsive iframe partner quote badge route.
    • Public pages: /about, /contact, /careers, /file-a-claim, /get-quote, /schedule-a-call, /locations, /locations/[slug], /refer-and-earn, /privacy-policy, /privacy-notice, /california-notice, /privacy-request-intake, /privacy-appeal, /sms-policy.
  • src/app/api: RESTful HTTP Route Handlers:
    • api/auth: NextAuth handler api/auth/[...nextauth], token validation, and email verification.
    • api/leads: Inbound HMAC-authenticated partner lead ingestion (/personal, /commercial-trucking).
    • api/forms: Endpoints for quote drafts (/quote/draft), quote completion (/quote/complete), contact, claims, calls, careers, waitlist, newsletter, and QR event leads.
    • api/meta: Meta Lead Ads management, single lead inspection, status updates, and reprocessing retries.
    • api/signatures: Public immutable image streaming endpoint /api/signatures/[id].
    • api/telemetry: Visitor heartbeat beacons, page views, journey steps, and blog read analytics.
    • api/webhooks: Inbound marketing lead webhooks for Meta Graph API, Google Ads, and TikTok.
    • api/docs: Interactive Swagger UI and raw OpenAPI specification (/api/docs/openapi.json).
    • api/health: Uptime and smoke-test probe returning JSON status.

3.2 Components Architecture (src/components)​

Components are divided strictly between generic UI primitives and domain features:

  • src/components/ui: Atomic primitives built on Tailwind CSS and Radix/Base UI (buttons, inputs, dialogs, badges, cards, image crop modals, lazy image loaders, carousel sliders).
  • src/components/feature: Feature-specific UI assemblies:
    • admin/: Admin dashboard, analytics charts, Tiptap blog editor, FAQ manager, QR event manager, bulk email campaign studio, audit log table.
    • dashboard/: Customer dashboard tabs, profile editor, avatar cropper, referral earnings, submission history explorer, draft resumption, submission inspector modal.
    • home/: Hero banner, quote intake modals, coverage carousels, intelligence section, trust badges, testimonials, dynamic FAQs.
    • insurance/: Unified 20-line insurance detail layout, coverage benefits, deductible breakdowns.
    • refer/: Public Refer & Earn landing page, referral calculator, reward step guides.
    • voice/: Web Speech Recognition assistant, Web Audio API 60 FPS canvas visualizer, voice command intent parser.
    • events/: Event attendee lead capture forms optimized for smartphone input at live conventions.

3.3 Core Libraries & Business Logic (src/lib)​

  • src/lib/db/: Mongoose connection manager (mongoose.ts) and the complete catalog of 40 schema models (src/lib/db/models/).
  • src/lib/auth.ts & auth-helpers.ts: NextAuth.js v5 beta configuration, Credentials provider, JWT callbacks, and server-side RBAC guards (requireAuth, requireAdmin, requireSuperAdmin).
  • src/lib/rate-limit/: Tiered MongoDB sliding-window rate limiter with automatic TTL document expiry.
  • src/lib/recaptcha-guard.ts & recaptcha.ts: Dual Google reCAPTCHA v2/v3 scoring engine and honey-pot evaluator.
  • src/lib/quarantine-manager.ts: Threat isolation manager quarantining suspicious submissions into MongoDB.
  • src/lib/hti-crm.ts: Downstream lead delivery client to the HTI CRM with Basic Auth and automated CrmFailedLead capture.
  • src/lib/hti-leads/: HMAC-SHA256 signature generator and verification logic for partner lead ingestion.
  • src/lib/emails/ & email.ts: Outbound email templating engine, bulk campaign dispatcher, Azure Email Function client, and Nodemailer fallback.

3.4 Server Actions (src/server/actions)​

Encapsulate all mutations and data fetching for internal components:

  • admin.actions.ts: Lead listing, pagination, status changes, metric aggregation.
  • auth.actions.ts: User sign-in, account registration, password reset flows.
  • blog.actions.ts: Article creation, Tiptap HTML persistence, publishing toggles.
  • bulk-email.actions.ts: Mass campaign scheduling, template library, recipient chunking.
  • lead.actions.ts: Quote draft autosaving, multi-step completion, downstream CRM triggers.
  • event.actions.ts: Campaign creation, QR code generation, attendee lead ingestion.
  • user-submissions.actions.ts: Customer dashboard submissions history and draft resumption queries.