first

docs/adr/ADR-0001-monorepo.md

@@ -0,0 +1,58 @@
+# 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.