Skip to main content

Monorepo Orchestration

A comprehensive reference for developers to manage the Elo Orgânico monorepo, infrastructure, and automation.

Running the Platform​

We use Turborepo and Docker Compose to orchestrate applications and their respective local infrastructure (databases and cache) in unified scripts.

  • Start Dev Stack: pnpm instance:dev (Starts local databases in Docker, then runs Web and API on the host)
  • Stop & Kill Ports: pnpm instance:down (Stops database containers and releases ports 3000 and 5173)
  • Reset Infrastructure: pnpm instance:reset (Stops, wipes MongoDB/Redis data volumes, and rebuilds containers)

Infrastructure (Docker)​

The project uses two Compose files per bounded context with strictly separated responsibilities.

Development Infrastructure (compose.dev.yaml)​

Starts only the local infrastructure services. Applications run on the host via pnpm *:dev.

ScopeCommandDescription
Instancepnpm instance:upStarts MongoDB (Replica Set) and Redis for Instance.
Instancepnpm instance:downStops Instance containers and kills ports 3000, 5173.
Instancepnpm instance:resetWipes volumes and restarts Instance infrastructure.
Portalpnpm portal:upStarts MongoDB (Replica Set) and Redis for Portal.
Portalpnpm portal:downStops Portal containers and kills ports 3001, 5174.
Portalpnpm portal:resetWipes volumes and restarts Portal infrastructure.

Production & Staging Stack (compose.prod.yaml)​

Builds and deploys the full application stack (API + Web/Nginx + Redis). No MongoDB — production connects to MongoDB Atlas. Production and staging reuse the same Compose file; only the --env-file differs.

ScopeCommandDescription
Instancepnpm instance:prodBuilds and starts Instance stack with .env.prod.
Instancepnpm instance:stagingSame stack with .env.staging (staging Atlas cluster).
Instancepnpm instance:prod:downStops the Instance production/staging stack.
Portalpnpm portal:prodBuilds and starts Portal stack with .env.prod.
Portalpnpm portal:stagingSame stack with .env.staging.
Portalpnpm portal:prod:downStops the Portal production/staging stack.

Workspace Management​

Handling internal dependencies, catalogs, compilation checks, and linting.

Global Orchestration (Turborepo)​

These commands execute in parallel across all active monorepo workspaces using the settings defined in turbo.json:

  • Typecheck All Workspaces: pnpm typecheck (Runs turbo run typecheck in parallel)
  • Lint All Workspaces: pnpm lint (Runs turbo run lint in parallel)
  • Clean node_modules: pnpm clean (Runs npkill to reclaim storage)
  • Add Dependency to Catalog: pnpm add <package> --catalog
  • Add Dependency to Specific App: pnpm add <package>@catalog: --filter <package-name>

Workspace-Specific Checks​

Run typechecks or linting only for a specific context boundary:

ContextTypecheck CommandLint Command
Instancepnpm instance:typecheckpnpm instance:lint
Portalpnpm portal:typecheckpnpm portal:lint
Studiopnpm studio:typecheckpnpm studio:lint
Toolspnpm tools:typecheckpnpm tools:lint
Integrated Linting & Formatting

We use eslint-plugin-prettier to integrate Prettier rules directly into ESLint for .ts, .tsx, .js, and .jsx files. Running any of the lint commands above will validate code quality and format code in a single step. Direct prettier CLI formatting is reserved for .json, .yaml, .md, and .mdx files.

AI & Studio (MCP)​

Orchestrating the Model Context Protocol and design bridge.

  • Penpot Studio: pnpm penpot:up / pnpm penpot:down
  • Aide AI Bridge: pnpm penpot:aide:up / pnpm penpot:aide:down
  • Context7 Search: (Via AI Agent) Deep research into documentation.

Build Pipelines​

  • Full Build: pnpm build
  • Build Core (Instance): pnpm --filter @elo-instance/core build
  • Build Core (Portal): pnpm --filter @elo-portal/core build

Last Updated: June 2026