Skip to main content

ADR-001: Use Nx Monorepo

Status​

Accepted

Date​

2026-07-20

Context​

Chilarai is the internal codename for CampusHub, a multi-tenant school management platform being developed by Ujan Labs.

The platform currently consists of:

  • Web application (Next.js)
  • Backend API (NestJS)
  • Shared TypeScript contracts
  • Shared runtime validation schemas

The platform is expected to expand over time to include background workers, reporting services, integrations, AI-assisted workflows, administrative applications, and additional supporting services.

As a small engineering team, it is important to balance rapid development with maintainability and long-term scalability.

A repository strategy must be selected before significant development begins.

Decision Drivers​

The selected approach should:

  • Minimize operational complexity
  • Support code sharing between applications
  • Support future platform growth
  • Simplify dependency management
  • Reduce duplicated code
  • Enable consistent tooling and workflows
  • Work well with TypeScript
  • Support a small team while scaling to a larger team in the future

Alternatives Considered​

Option 1: Multiple Independent Repositories​

Example structure:

  • chilarai-web
  • chilarai-api
  • chilarai-shared-types
  • chilarai-shared-validation

Advantages​

  • Clear ownership boundaries
  • Independent release cycles
  • Smaller repositories
  • Separate permissions can be applied per repository

Disadvantages​

  • Shared contracts require package publishing or duplication
  • Shared validation schemas become harder to maintain
  • Cross-cutting changes require multiple pull requests and releases
  • Increased CI/CD complexity
  • Increased repository administration overhead
  • More difficult for a small team to manage

Assessment​

This option provides strong isolation but introduces significant operational overhead. The benefits do not justify the complexity at the current size of the team.

Option 2: Single Repository Without Monorepo Tooling​

Example structure:

  • web
  • api
  • shared

Advantages​

  • Simple repository structure
  • Single repository
  • Minimal tooling requirements
  • Easy initial setup

Disadvantages​

  • No dependency graph awareness
  • No affected build or test execution
  • Manual build orchestration
  • Reduced visibility into project relationships
  • More difficult to scale as applications and libraries increase

Assessment​

This option is simple initially but is likely to require additional custom tooling as the platform grows.

Option 3: Nx Monorepo​

Example structure:

  • web
  • api
  • api-e2e
  • shared-types
  • shared-validation

Advantages​

  • Single repository
  • Shared code without package publishing
  • Project dependency graph
  • Consistent developer experience
  • Incremental and affected builds
  • Shared testing infrastructure
  • Strong TypeScript support
  • Suitable for both startup and scale-up phases

Disadvantages​

  • Additional tooling complexity
  • Learning curve for contributors unfamiliar with Nx
  • Dependency on the Nx ecosystem
  • Repository size increases over time

Assessment​

This option provides the best balance between startup agility and long-term maintainability.

Decision​

Use an Nx monorepo as the primary repository structure for Chilarai.

Rationale​

The platform requires close coordination between frontend, backend, shared contracts, and shared validation logic.

Using an Nx monorepo allows:

  • Direct sharing of TypeScript contracts between applications
  • Direct sharing of validation schemas between applications
  • Consistent tooling across projects
  • Unified dependency management
  • Easier refactoring across application boundaries
  • Simplified onboarding for new contributors

A multi-repository approach introduces publishing, versioning, and coordination overhead that is not justified at the current scale.

A plain repository without monorepo tooling provides insufficient support for dependency management and build optimization as the platform grows.

Nx offers appropriate structure and tooling without introducing unnecessary operational complexity.

Consequences​

Positive Consequences​

  • Single source of truth for shared code
  • Reduced duplication
  • Easier cross-project refactoring
  • Consistent development workflows
  • Simplified dependency management
  • Simplified CI/CD strategy
  • Better support for future platform growth

Negative Consequences​

  • Contributors must understand Nx concepts and tooling
  • Repository size will increase over time
  • Project structure becomes dependent on Nx conventions

Follow-up Actions​

  • Use shared-types for shared TypeScript contracts
  • Use shared-validation for shared runtime validation schemas
  • Keep shared libraries minimal until concrete usage exists
  • Add CI validation for build, lint, and test workflows
  • Re-evaluate repository strategy if services become independently owned