Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
AtlasCleanAI Enterprise organizes its codebase into a single repository to manage an AI-powered cleaning services platform. The architecture integrates a Node.js backend, Flutter-based mobile packages, and cloud infrastructure definitions for AWS using both CDK and Terraform. It facilitates local development via Docker Compose and ensures consistency across service tiers through shared design and API client packages.
Sources: README.md:1-26, package.json:1-15
Repository Structure
The monorepo separates concerns into distinct directories for applications, shared logic, and infrastructure.
| Directory | Content Description |
|---|---|
.github/workflows/ | CI/CD pipelines for staging and production. |
backend/ | Node.js API server using Express and Prisma. |
infrastructure/ | AWS CDK, Terraform, Docker, and NGINX configurations. |
packages/ | Shared Dart/Flutter code for UI components and API clients. |
docs/ | Technical guides for architecture, API, and deployment. |
Sources: README.md:28-40, backend/package.json:1-10
Application Architecture
The platform follows a layered service model. A Node.js backend serves as the core API, interacting with PostgreSQL for persistence and Redis for caching.
The diagram shows the flow from client applications through the ingress layer to the core API and data persistence layers.
Sources: README.md:42-53, backend/src/app.ts:182-212
Backend Module Organization
The backend implements a Clean Architecture pattern, separating domain logic from infrastructure and interfaces. It uses AppDependencies to inject repositories and services into controllers and use-cases.
- Interfaces: Contains Express controllers, routes, and middleware like
auth.middleware.tsandvalidation.middleware.ts. - Application: Defines use-cases such as
CreateBookingUseCaseandLoginUseCase. - Domain: Houses entities (e.g.,
Booking,Cleaner) and repository interfaces. - Infrastructure: Implements database access via Prisma, external services (Stripe, Firebase, Atlas AI), and configuration.
Sources: backend/src/app.ts:7-60, backend/src/app.ts:133-180
Data Schema
The system uses a relational schema managed by Prisma. The primary entities include Users, Cleaners, Bookings, and Payments.
This diagram illustrates the relationships between core entities within the PostgreSQL database.
Sources: backend/src/infrastructure/database/prisma/schema.prisma:45-135
Infrastructure and Deployment
The monorepo provides two primary methods for cloud infrastructure provisioning: AWS CDK and Terraform. Both methods deploy the application into a VPC with isolated tiers.
Network Segmentation
Both infrastructure options enforce a three-tier network architecture:
- Public Subnets: Host the Application Load Balancer (ALB).
- Application Subnets: Host ECS Fargate containers running the Node.js backend.
- Data Subnets: Host isolated RDS (PostgreSQL) and ElastiCache (Redis) instances.
Sources: infrastructure/aws/cdk/lib/atlasclean-stack.ts:40-63, infrastructure/terraform/main.tf:45-84
Resource Configuration
| Resource | Service / Implementation | Environment Differences |
|---|---|---|
| Compute | AWS ECS Fargate | Scaling: 1-3 (Staging) vs 2-8 (Production) |
| Database | Amazon RDS PostgreSQL 15.5 | Multi-AZ and Deletion Protection in Production |
| Cache | Amazon ElastiCache Redis 7.1 | Transit and At-Rest encryption enabled |
| Secrets | AWS Secrets Manager | Managed via DatabaseSecret and specific JWT keys |
Sources: infrastructure/aws/cdk/lib/atlasclean-stack.ts:108-163, infrastructure/terraform/main.tf:190-250
Development Workflow
Local development is orchestrated through docker-compose.yml, which mirrors the production stack by spinning up local instances of PostgreSQL, Redis, NGINX, and the backend API.
The sequence shows the local environment initialization and the dependency management between services.
Sources: docker-compose.yml:7-65, backend/package.json:7-15
Shared Packages
The monorepo includes shared packages in the packages/ directory to maintain consistency across Flutter applications:
- atlas_design_system: Defines brand colors, typography, and reusable UI components.
- atlas_api_client: Provides a standardized Dart client for communicating with the backend API, handling JSON parsing and authentication.
Sources: README.md:120-134, packages/atlas_design_system/pubspec.yaml:1-10
Conclusion
The AtlasCleanAI Enterprise Monorepo Architecture provides a unified environment for managing the full lifecycle of an AI-driven service platform. By centralizing infrastructure, shared logic, and API definitions, the project ensures environment parity between local development and AWS cloud deployments while maintaining strict security through network isolation and secret management.