Development & Configuration
Local development, validation, and configuration guidance for the web app.
Development & Configuration
Run Web App commands from main/, not from this documentation repository. The application requires its own dependencies, PostgreSQL/Prisma configuration, Model Server connectivity, and the shared-data mount used by the integrated runtime.
Local Development Checklist
- Use the package manager and Node.js version committed by
main/; do not mix lockfiles. - Copy the Web App's environment template, keeping secrets only in an uncommitted local environment file.
- Start PostgreSQL and any required integrated services using the root Compose configuration.
- Configure the Web App's Prisma connection and apply the repository's migrations before starting the app.
- Generate the Prisma client and run the project's seed command if the workflow needs reference data.
- Start the Web App and confirm that its browser workflow can reach the Model Server only through the configured server-side URL.
Use the scripts defined by main/package.json as the authoritative commands. The expected workflow includes development, production build, linting, Prisma client generation, migrations, and (where configured) seeding. Run the Web App's lint, type-check, and build checks before a change is merged.
Environment Variables
The exact environment-file names and values belong to the main/ repository. These are the integration settings that must be present and must remain server-only:
| Setting | Purpose | Handling requirement |
|---|---|---|
| PostgreSQL / Prisma connection | Connects the Web App to the database it owns. | Keep credentials out of source control and point local development at the intended database. |
MODEL_API_URL | Base Model Server URL, including its /api prefix. | Server-only; use a private service address in deployed environments. |
| Model Server bearer credential | Authenticates Web App requests to the Model Server (MODEL_API_TOKEN / API_BEARER_TOKEN are the documented paired credentials). | Server-only; rotate both consumers together. |
MAIN_APP_API_KEY | Authenticates Model Server callback delivery to the Web App. | Server-only; do not log or expose it. |
| Shared-data configuration | Resolves uploaded inputs and generated outputs to the shared mount. | Must agree with the Model Server and workers. |
| Email and realtime settings | Deliver completion notifications and realtime updates. | Treat provider keys and recipient data as sensitive. |
Never prefix service credentials, provider keys, uploaded-data locations, or callback secrets with NEXT_PUBLIC_. The canonical cross-service values and rotation rule are in Operations and Security Boundaries.
Database and Prisma
PostgreSQL holds the Web App's users, datasets, files, jobs, and notifications. Prisma is the database boundary for the Next.js application; the schema and migration history in main/ are authoritative.
For a new local database, apply existing migrations rather than recreating tables manually. Generate the Prisma client after dependency or schema changes, then use the repository's seed path only when it is explicitly provided. Do not use a shared development or production database for exploratory migrations.
When changing a model that participates in analysis, collection, report, or file workflows, review whether a callback payload, status mapping, or shared-storage reference also changes. If it does, follow the compatible-change process in Cross-Repository Contracts.
Shared Data in Local Environments
The integrated runtime mounts main/shared-data into the Web App, Model Server, and workers at /app/shared-data. Database fields and service requests use forward-slash paths relative to the service root, such as shared-data/collected-data/<jobId>.csv; never store a host-specific absolute path.
Before testing uploads, collection, analysis, or reports, confirm that each container resolves the same files through this mount. A local path that works only in the Web App container will fail when a worker processes the job.
Troubleshooting
| Symptom | Likely check |
|---|---|
| Prisma cannot connect or migrations fail | Verify the Web App database URL, that PostgreSQL is running, and that the target database is the intended local environment. |
A job remains pending | Check Web App validation and the request to the Model Server. A job should become enqueued only after the service accepts it. |
A job stays enqueued or started | Check Redis, the appropriate worker queue, worker logs, and callback delivery. |
| Worker reports a missing input file | Confirm the relative shared-data/ path and that the Web App, Model Server, and worker share the configured mount. |
| A completed report cannot be downloaded | Check the file-specific generated-report directory and the Web App authorization check for the requested FileMeta. |
| A callback is rejected or missing | Verify the private service route, callback credential configuration, stable job/file ID, and redacted notification-worker logs. |