Infrastructure & Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Comply-Quick is built as a multi-tier web application utilizing a Next.js frontend and a specialized standalone worker service for headless browser operations. The infrastructure is designed to be modular, leveraging containerization for consistent deployment across different environments such as Vercel and Fly.io.
The system separates standard web serving from resource-intensive browser rendering. This ensures that the primary user interface remains performant while the "Scanner Worker" handles complex JavaScript execution and tracker detection tasks.
System Architecture
The project architecture consists of two primary components: the Next.js application (client/server) and the Scanner Worker (headless browser service).
The diagram shows the flow of a compliance scan from the user interface through the backend pipeline to the specialized worker service.
Sources: scanner-worker/README.md:1-10, src/lib/scanner/pipeline.ts:1-10
Next.js Application
The core application is built with Next.js 16 and React 19. It handles user authentication, dashboard management, compliance logic, and payment processing via Stripe.
Sources: package.json:28-36, src/app/page.tsx
Scanner Worker Service
The Scanner Worker is a standalone service that uses a headless browser (Chromium) to render URLs. Unlike a standard server-side fetch, it executes JavaScript to detect "late-firing" tags and injected trackers like Meta Pixel or Google Analytics.
Sources: scanner-worker/README.md:1-6, src/tests/scanner.test.ts:108-115
Deployment Configuration
The application is configured for deployment using modern cloud platforms. The primary frontend typically resides on Vercel, while the worker is designed for containerized hosts like Fly.io or Railway.
Environment Variables
Key configuration options are managed through environment variables to secure secrets and define service endpoints.
| Variable | Source | Purpose |
|---|---|---|
NEXT_PUBLIC_SITE_URL | src/app/page.tsx | Base URL for SEO and canonical links. |
SCANNER_WORKER_URL | scanner-worker/README.md | Endpoint for the headless browser service. |
SCANNER_WORKER_SECRET | scanner-worker/README.md | Shared bearer token for API authentication. |
SCAN_NAV_TIMEOUT_MS | scanner-worker/README.md | Maximum navigation time for browser scans. |
SCAN_SETTLE_MS | scanner-worker/README.md | Delay to wait for late-firing tags (Default: 2500ms). |
Sources: scanner-worker/README.md:21-27, src/app/page.tsx:6
Headless Worker Scaling
The worker service is decoupled to allow independent scaling. It can be deployed via Docker or directly to Fly.io using the provided configuration.
# Example Deployment to Fly.io
fly launch --no-deploy
fly secrets set SCANNER_WORKER_SECRET=<secret>
fly deploy
Sources: scanner-worker/README.md:46-51
Development & CI/CD Standards
The project enforces strict operational guardrails to maintain code quality and deployment reliability.
Operational Guardrails
- TypeScript Strictness:
strict: truemust never be disabled, and implicitanyis forbidden. - Path Constraints: Parentheses are strictly forbidden in file or directory paths (e.g., no Next.js Route Groups like
(auth)). - Quality Checks: A pre-commit/pre-deployment suite runs type checking, linting, and Vitest-based unit testing.
Sources: devin/instructions.md:5-15, 33-39, package.json:7-14
Testing Framework
The infrastructure supports three main testing tiers:
- Unit Testing: Using Vitest for core logic like the
ClauseEngine. - Integration Testing: Testing the communication between the app and the Scanner Worker.
- Phase-based Validation: Documented test plans for major features (e.g., Stripe, SEO, Command Center).
Sources: src/tests/scanner.test.ts, test-plan-phase6.md
Scanner Pipeline Logic
The system includes a transparent fallback mechanism to ensure high availability. If the specialized worker is unreachable, the system falls back to a standard static fetch.
The sequence diagram illustrates the resilience of the scanning infrastructure, showing the worker path and the fallback static fetch path.
Sources: src/lib/scanner/crawler.ts:1-20, src/tests/scanner.test.ts:130-145
Conclusion
The infrastructure of Comply-Quick is built for reliability and technical depth, separating the "shallow" web app needs from the "deep" resource-intensive requirements of compliance scanning. By utilizing a containerized worker for headless browsing and strict TypeScript standards for the core application, the system maintains a robust and scalable architecture suitable for agency-level production.