Atlas is a full‑stack web application developed by Recursion Labs. It consists of a Node/Express API (under the app/ folder), a Next.js frontend (under web/), and infrastructure managed via Terraform (infra/). The repository is structured using Turborepo for monorepo management.
The project is divided into several logical areas:
app/– Backend service written in TypeScript using Express. Includes controllers, middleware, models, and configuration.web/– Frontend built with Next.js and TailwindCSS. It provides UI components, pages, and global styles.infra/– Terraform configurations for provisioning cloud resources (Google Cloud / Firebase, Cloud Run, Firestore, etc.).pkg/– Shared TypeScript definitions and utilities, such as environment variables and custom prompts.__test__/– Integration or end‑to‑end tests (simple HTML file present in repo).scripts/– Utility scripts used during development or deployment.keys/– Service account credentials and Terraform state keys (excluded from source control).
Each workspace folder (app, web, infra) contains its own package.json or configuration to allow independent development while still benefiting from shared tooling.
- Node.js (20.0.x or later recommended)
- Yarn (preferred) or npm
- Terraform (for infrastructure)
- Google Cloud credentials (a service account JSON file located in
keys/googleServiceAccount.json) tf-key.jsonfor encrypting Terraform state (managed outside version control)
-
Clone the repository and install dependencies at the root:
git clone https://github.com/Recursion-Labs/atlas.git cd atlas yarn install # or: npm install
-
Install packages for each workspace if you prefer independent installs:
cd app && yarn install cd ../web && yarn install
-
Create a
.envor configure environment variables as needed. Seepkg/config/envVars.tsfor expected keys.
cd app
# start in development mode with nodemon
npm run dev
# or yarn devThe backend listens on port 3001 by default and exposes routes under /api (see app/routes/**). Swagger documentation is available at /swagger.json and served by swagger.js.
cd web
npm run dev
# or yarn devNext.js starts on port 3000. Open http://localhost:3000 to view the application. Modify components under web/app/components.
Turborepo commands can orchestrate tasks across packages:
npx turbo run build # build all workspaces
npx turbo run lint
npx turbo run test- Configuration –
app/configcontains environment, logging, and Firebase setup. - Controllers –
app/controllershandle incoming HTTP requests (e.g.auth.controller.ts,user.controller.ts). - Routes – Organized by feature under
app/routeswith nested modules for auth and user. - Middleware – e.g.
auth.middleware.tsto protect routes using JWT or Firebase auth. - Models –
user.model.tsdefines data shapes and interacts with Firestore or other storage. - Services – Business logic lives here (folder present but may be empty or fleshed out).
- Handlers –
async.handlers.tsanderror.handlers.tscentralize promise handling and error responses.
The backend uses tsconfig.json with path aliases defined in moduleAlias.ts for cleaner imports.
- The Next.js app follows the App Router paradigm with
app/layout.tsxandapp/page.tsx. - Global styles are in
app/globals.css. - Each feature (e.g. command-center) has its own folder under
app. - UI components like
Navbar,Hero, andGlobeVieware reusable and pulled into pages. - TypeScript is configured via
tsconfig.json, and additional type definitions live inpkg/@types.
This package contains:
- @types/config.d.ts – Type definitions for environment variables.
- config/envVars.ts – Utility to load/validate environment variables.
- prompts/ – Custom CLI prompt definitions (used by scripts or dev tooling).
These modules are referenced using workspace aliases and help maintain DRY principles.
Terraform is used to provision the following resources in a Google Cloud project:
- Cloud Run services for backend and frontend (if containerized)
- Firestore database
- IAM roles and service accounts
- Other components may include Pub/Sub, Storage buckets, etc.
Folder hierarchy:
infra/
environments/
dev/ # development-specific tf state and variables
prod/ # production configuration
modules/ # reusable Terraform modules, e.g., cloudrun, firestore
vars.tf
versions.tf # Terraform provider versions
To deploy infrastructure:
cd infra/environments/dev
terraform init
terraform plan -var-file="terraform.tfvars"
terraform apply -var-file="terraform.tfvars"
⚠️ State files (e.g.terraform.tfstate) are not checked into version control in prod. Use remote backends (GCS or Terraform Cloud) for collaboration.
- Unit and integration tests should reside under
__test__/or within each package's testing framework. - Linting, formatting, and type checking are configured via
package.jsonscripts andtsconfig.json. - Run all checks with:
yarn lint yarn typecheck yarn test
- Frontend – Deployed via Next.js build output. Could be hosted on Vercel, Cloud Run, or static hosting.
- Backend – Built into a Docker container and deployed to Cloud Run (see
infra/modules/cloudrun). - CI/CD pipelines are defined in
.github/workflowsor similar (not shown in repo). Use GitHub Actions or other tools to automate.
Examples of commands in scripts/:
bootstrap.sh– set up environment variablesdeploy.sh– kick off a manual deploy
Inspect the
scripts/directory for project-specific helpers.
- Fork the repo and create a feature branch.
- Run linting and tests before submitting a PR.
- Ensure code follows the existing style and includes documentation where appropriate.
Please refer to CONTRIBUTING.md (if present) for detailed guidelines.
This project is licensed under the MIT License. See the LICENSE file for details.
For questions, reach out to the Recursion Labs team. Happy coding!