# 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.