Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• docker-compose.yml
• package.json
• backend/package.json
• backend/src/config/index.ts
• infrastructure/nginx/nginx.conf
• server.js

Local development for AtlasCleanAI Enterprise relies on a containerized infrastructure to manage dependencies and application services. This setup enables developers to run the full stack—including the Node.js backend, PostgreSQL database, Redis cache, and NGINX reverse proxy—on a local workstation using Docker Compose.

Sources: README.md:21-28, docker-compose.yml:8-60

Prerequisites

Before starting the local environment, you must install the specific software versions required by the platform:

• Docker Engine: Version 24 or newer.
• Docker Compose: Version v2 or newer.
• Node.js: Version 22 LTS or newer.
• Flutter: Version 3.13 or newer (for mobile applications).

Sources: README.md:61-68, package.json:20-22

Infrastructure Components

The local environment consists of four primary services orchestrated via Docker. These services provide the foundation for transactional data, caching, and request routing.

Service Architecture

The following diagram illustrates how local traffic flows from the developer's machine through the NGINX proxy to the internal services.

The diagram shows the local network relationships defined in the Docker Compose configuration.
Sources: docker-compose.yml:8-60, infrastructure/nginx/nginx.conf:65-71

Local Service Definitions

Service	Image	Local Port	Role
postgres	postgres:15-alpine	5432	Stores transactional data for bookings, users, and services.
redis	redis:7-alpine	6379	Manages caching, sessions, and background work orchestration.
backend	Custom (Dockerfile.backend)	3000	Serves the Enterprise API and Atlas AI chat integration.
nginx	nginx:alpine	80 / 443	Terminates TLS and acts as a reverse proxy for the backend.

Sources: docker-compose.yml:8-60, README.md:78-83

Initialization Procedures

You can start the environment in two modes depending on whether you are working on application code or infrastructure.

1. Start Supporting Services Only

Use this mode if you plan to run the Node.js backend or Flutter apps natively on your host machine while using containerized databases.

docker compose up -d postgres redis nginx

Sources: README.md:70-72

2. Start the Full Stack

Use this mode to run all components, including the backend, inside Docker containers.

docker compose up --build

Sources: README.md:74-76

Configuration and Environment Variables

The application requires specific environment variables to connect to local services. These are typically managed via a .env file or supplied directly to Docker Compose.

Core Backend Settings

Variable	Requirement	Default / Purpose
NODE_ENV	Required	development
DATABASE_URL	Required	postgresql://atlasclean:password@postgres:5432/atlasclean_db
REDIS_URL	Required	redis://redis:6379
JWT_SECRET	Required	Secret for signing access tokens.
JWT_REFRESH_SECRET	Required	Secret for signing refresh tokens.
PORT	Optional	Defaults to 3000 or 4000 depending on context.

Sources: README.md:85-91, backend/src/config/index.ts:74-85, docker-compose.yml:37-43

Atlas AI Integration

To enable the AI chat feature locally, you must provide an OpenAI API key.

• File: .env (copied from .env.example)
• Variable: OPENAI_API_KEY
• Optional: ATLAS_API_KEY (to protect local endpoints with x-api-key header).

Sources: README.md:93-108, server.js:1-10

Development Workflow Commands

The package.json files in the root and backend/ directories provide scripts for common development tasks.

Backend Scripts

Execute these from the backend/ directory:

• npm run dev: Starts the server with ts-node-dev and auto-reload.
• npm run db:migrate: Applies Prisma database migrations.
• npm run test: Runs the Jest test suite with coverage.
• npm run lint: Checks TypeScript code for style and errors.

Sources: backend/package.json:6-16

Root Scripts

Execute these from the repository root:

• npm start: Runs node server.js.
• npm run dev: Runs node --watch server.js for local chat UI development.
• npm test: Executes the Node.js internal test runner on test/app.test.js.

Sources: package.json:7-11

Network and Ingress Configuration

Local ingress is handled by NGINX, which proxies requests to the backend service. It includes rate limiting and security headers to simulate a production environment.

• API Proxy: Requests to http://localhost/ are forwarded to the internal atlas_backend upstream at port 3000.
• Rate Limiting: Configured at 20 requests per second with a burst of 40.
• Security Headers: Includes X-Content-Type-Options: nosniff and X-Frame-Options: DENY.
• Health Check: A local endpoint at /healthz returns a 200 OK status.

Sources: infrastructure/nginx/nginx.conf:45-88

Summary

The local setup provides a mirrored environment of the cloud architecture using Docker Compose. By providing working defaults for PostgreSQL and Redis, developers can focus on application logic in the backend/ or packages/ directories. All secrets should be maintained in a local .env file and never committed to source control.

Sources: README.md:88-91, README.md:186-191