ADR-0001 — Monorepo Structure for ASF

Status: Accepted
Date: 2026-09-07
Deciders: ASF Architecture Team

Context

Azurian Software Factory comprises several logical components: a shared domain model, an event schema package, connectors, multiple backend services (core, context, ai, worker) and a Next.js web frontend.

We must choose a repository organization that balances:

Strong cohesion for shared types / contracts
Independent deployability of services
Local developer ergonomics
Clear service boundaries

Decision

Use a single monorepo with the following top-level layout:

ASF/
├── frontend/asf-web/          # Next.js SaaS UI
├── services/                  # Deployable Python services
│   ├── asf-core/
│   ├── asf-context/
│   ├── asf-ai/
│   └── asf-worker/
├── packages/                  # Shared installable Python packages
│   ├── asf-domain/
│   ├── asf-events/
│   └── asf-connectors/
├── docs/                      # Architecture, ADRs, API docs
├── infrastructure/            # Dockerfiles, scripts
└── tests/                     # Cross-service integration tests

Shared packages are installed in editable mode (pip install -e) when developing locally.

Consequences

Positive

Shared domain models and event schemas live in one place — no drift.
Refactors that cross service boundaries are done atomically in one PR.
Local docker-compose up brings up the whole stack trivially.
Search / navigation works across the whole product.

Negative

CI pipelines must be careful to only rebuild what changed.
Service release tagging must be explicit (single git log, many artefacts).

Risks / Mitigations

Accidental tight coupling between services → mitigated by code review, AGENT.md rules, and keeping services import only from packages/*, never from each other.

1.9 KiB Raw Permalink Blame History