atelier/.ciagent/atelier/ARCHITECTURE.md

Atelier — Architecture

System Overview

Atelier is a documentation-only framework — no runtime code, no build artifacts. The "system" is the document tree itself and the relationships between documents.

Component Boundaries

atelier/
├── core/                       # Universal principles — the foundation
├── domains/                    # Domain-specific application of core
│   ├── ... (v0.1: 11 domains)
│   ├── infrastructure-as-code/ # v0.2: IaC tooling (terraform, opentofu, state, modules)
│   ├── kubernetes/             # v0.2: k8s platform (workloads, networking, storage, rbac, helm, kustomize)
│   ├── gitops-operators/       # v0.3: GitOps + Operators (argocd, flux, operators, progressive-delivery)
│   ├── ai-ml/                  # v0.3: ML engineering (data-versioning, model-evaluation, serving, monitoring-drift)
│   ├── i18n/                   # v0.3: internationalization (locale-resources, formatting, rtl-bidi, testing-i18n)
│   ├── compliance/             # v0.3: compliance/audit (audit-logs, data-retention, policy-as-code, evidence)
│   ├── edge/                   # v0.4: edge computing (cdn, offline-first, iot, sync)
│   └── messaging/              # v0.4: cross-process messaging (queues, pubsub, streams, delivery-semantics)
├── languages/                  # Language-specific application of domains
│   ├── typescript.md           # v0.1 first-principles stub
│   ├── python.md               # v0.1 first-principles stub
│   ├── go.md                   # v0.1 first-principles stub
│   ├── rust.md                 # v0.1 first-principles stub
│   ├── ts-*.md                 # v0.4: 4 derived docs (ts-types, ts-tooling, ts-async, ts-testing)
│   ├── py-*.md                 # v0.4: 4 derived docs (py-types, py-tooling, py-async, py-testing)
│   ├── go-*.md                 # v0.4: 4 derived docs (go-types, go-tooling, go-concurrency, go-testing)
│   └── rs-*.md                 # v0.4: 4 derived docs (rs-ownership, rs-tooling, rs-async, rs-testing)
├── review/                    # Evaluation checklists and anti-patterns
├── matrix/                    # Cross-reference: domain ↔ core
└── examples/                  # Worked examples (good + bad)

Dependency direction (enforced):

• core/ depends on nothing
• domains/ depend on core/ (each domain's P-rules trace to core C-rules)
• languages/ depend on domains/ (language rules apply domain rules)
• matrix/ depends on core/ + domains/ (it's the join table)
• review/ depends on everything (it evaluates compliance)
• examples/ depend on everything (they illustrate)

No document may reference a sibling at the same level as authoritative — conflict resolution always goes UP to core.

Data Flow

There is no runtime data flow. The "flow" is the reading order:

1. core/first-principles.md (required first)
2. core/conflict-resolution.md (required)
3. domains/<relevant>/first-principles.md (per task)
4. domains/<relevant>/<topic>.md (as needed)
5. matrix/principles-matrix.md (reference)

Conflict Resolution Architecture

When two documents disagree:

1. Higher in the hierarchy wins (core > domains > languages)
2. Within a level, the more specific document wins for its scope
3. If still ambiguous, the core principle with the highest precedence (C1 Correctness > C2 Clarity > ...) wins
4. The matrix/principles-matrix.md is the arbiter — it records which core principle each domain rule derives from

Technology

• Format: Markdown (CommonMark + GitHub Flavored)
• Versioning: Whole-framework semantic versioning (one version per release, not per-doc)
• Distribution: Git repository (consumed by reading markdown)
• No build step — markdown is the artifact

Governance

• .ciagent/ holds project management artifacts (config, PROJECT.md, ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md, PERSONAS.md, PLAN)
• The framework content lives in the repo root (README.md, core/, domains/, etc.)
• MANIFEST.md is the authoritative index — unlisted documents are not part of the framework

Research-Refined Decisions

• 8 core principles (not 10): The spec's matrix key names exactly 8 (C1–C8). Each domain has 10 (P1–P10). Asymmetry is intentional — core is minimal, domains are specific.
• Numeric precedence C1 > C2 > ... > C8: Correctness is non-negotiable; Economy is the most tradeable.
• Strict hierarchy enforcement: No lateral authority. Conflicts go UP, never sideways.
• No build step: Markdown is the artifact. A build step would violate docs-as-code simplicity.

Prior Art Position

Atelier's differentiation: traceable principle hierarchy with a join table. Existing frameworks (ThoughtWorks Radar, Google Eng Practices, SOLID, 12-Factor, OWASP, WCAG) state principles; none provide a matrix mapping every domain rule back to a core rule. This makes Atelier's matrix/principles-matrix.md the conflict-resolution arbiter — the framework's unique value.

v0.2 Domain Additions

Two new top-level domains extend the tree under the same hierarchy rules:

• infrastructure-as-code/ — tooling domain. First principles govern declarative provisioning (terraform, opentofu, state, modules). Depends on core/. Cross-links to devops/ (P1 Reproducibility, P6 Configuration as Code) and security/ (supply-chain, secrets).
• kubernetes/ — platform domain. First principles govern container orchestration (workloads, networking, storage, rbac, helm, kustomize). Depends on core/. Cross-links to devops/ (P4 Rollback First, P5 Progressive Delivery), security/ (authorization, secrets), observability/ (metrics, tracing), data/ (storage patterns).

Both domains follow the v0.1 contract: 10 P-rules each, every rule traced to a core C-rule via the matrix, no orphans. The manifest (MANIFEST.md) is extended to keep them authoritative. No runtime code — examples are illustrative markdown with manifests in code fences only.

See .ciagent/atelier/RESEARCH.md for the full prior-art survey and .ciagent/atelier/PERSONAS.md for the persona roster (3 custom active personas + 1 phase-specific platform-engineer; 3 default personas deactivated).

v0.3 Domain Additions

Four new top-level domains extend the tree under the same hierarchy rules. All four follow the v0.1/v0.2 contract: 10 P-rules each, every rule traced to a core C-rule via the matrix, no orphans, docs-only markdown with illustrative code fences (no runtime/deployable artifacts). Total matrix grows from 130 → 170 domain principles across 13 → 17 domains.

• gitops-operators/ — platform-automation domain. First principles govern the declarative-source-of-truth reconciliation loop shared by ArgoCD, Flux, Kubernetes Operators, and Progressive Delivery tooling (Argo Rollouts, Flagger). Depends on core/. Cross-links to kubernetes/ (workloads, rbac, helm, kustomize — the platform GitOps reconciles onto), infrastructure-as-code/ (declarative intent, state-as-truth — the shared model), devops/ (P1 Reproducibility, P4 Rollback First, P5 Progressive Delivery, P6 Configuration as Code), security/ (secrets, supply-chain — GitOps credentials, signed manifests), observability/ (reconciliation metrics, drift visibility). Derived docs: argocd.md, flux.md, operators.md, progressive-delivery.md.
• ai-ml/ — ML engineering domain (engineering discipline, NOT algorithm design per D-023). First principles govern data versioning, model evaluation, serving, and monitoring/drift. Depends on core/. Cross-links to data/ (schema-design, migrations, indexing — data lineage and versioning share the migration/reversibility model), observability/ (metrics, tracing — model serving metrics, drift signals), devops/ (P1 Reproducibility — training/serving reproducibility, P7 Immutability — model images), security/ (input-validation — inference input validation, secrets — model/serving credentials), performance/ (backend — serving latency). Derived docs: data-versioning.md, model-evaluation.md, serving.md, monitoring-drift.md.
• i18n/ — internationalization domain. First principles govern locale resources, formatting, RTL/bidi layout, and testing. Depends on core/. Cross-links to uiux/ (components, accessibility, copywriting — locale-aware UI is the consumer), testing/ (fixtures, pyramid — i18n testing parallels), api/ (error-responses — localized API errors), data/ (schema-design — locale data shapes). Derived docs: locale-resources.md, formatting.md, rtl-bidi.md, testing-i18n.md.
• compliance/ — compliance/audit domain (framework-agnostic, NOT regulation-specific per D-024). First principles govern audit logs, data retention, policy-as-code, and evidence collection. Depends on core/. Cross-links to security/ (authorization — who did what, secrets — audit log integrity, supply-chain — signed policy), observability/ (logging, metrics — audit logs are a structured-logging concern, tracing — evidence from distributed traces), data/ (schema-design, migrations — retention schema), infrastructure-as-code/ (policy-as-code parallels IaC declarative intent), kubernetes/ (rbac — audit subject identity). Derived docs: audit-logs.md, data-retention.md, policy-as-code.md, evidence.md.

All four domains depend on core/ only for authority; cross-links to existing domains are one-directional (per v0.2 D-026 convention extended to v0.3 — minimize churn to existing content). The manifest (MANIFEST.md) is extended in P4 to list all new documents. Examples (P5) are illustrative markdown with fenced code only — no .yaml, .json, .po, model artifacts, or deployable manifests as standalone files.

v0.3 Ideation Architectural Notes

From the v0.3 ideation stage (IDEATE-17..30), the following architectural refinements are baked into the execute-phase plan:

• Manifest scope expansion (IDEATE-17 → ATELIER-91): the v0.2 audit escalation (ESC-002 note) flagged that examples/ is not listed in MANIFEST.md. P4 adds an examples/ directory listing to the manifest, closing the pre-existing drift. The manifest remains authoritative; unlisted directories are not part of the framework by definition.
• Matrix coverage summary invariants (IDEATE-18 → ATELIER-80): the matrix coverage summary must reflect post-v0.3 totals (17 domains, 170 P-rules) — both the summary block and the per-domain section count.
• Core Principle Coverage table (IDEATE-19 → ATELIER-81): matrix/domain-coverage.md contains two tables — the per-domain row schema table (covered by v0.2 IDEATE-03) AND the "Core Principle Coverage" table mapping C1–C8 → domains. Both must be extended for the 4 new domains; the C-rule counts shift (e.g., C4 Locality adds i18n + gitops; C5 Reversibility adds ai-ml + compliance + gitops + i18n).
• Cross-link type unchanged: v0.3 introduces no new cross-link type. All cross-links remain one-directional outward from new domains to existing (D-033). No back-link edits to v0.1/v0.2 content.

See .ciagent/atelier/RESEARCH.md "v0.3 Research" for the full prior-art survey and principle inventory rationale, and .ciagent/atelier/PERSONAS.md for the v0.3 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific platform-engineer, ml-engineer; 3 default personas deactivated).

v0.4 Domain Additions

Two new top-level domains and a language-derived extension expand the tree under the same hierarchy rules. All follow the v0.1/v0.2/v0.3 contract: docs-only markdown with illustrative code fences (no runtime/deployable artifacts per D-020). Total matrix grows from 170 → 190 domain principles across 17 → 19 domains.

• edge/ — edge computing domain. Owns the proximity/location/constraint angle (D-061): compute near the user or data source, offline as a first-class state, constrained resources declared, sync conflicts bounded, partition-survivable telemetry. Boundary vs performance/ (generic measurement/optimization), observability/ (generic structured telemetry), and concurrency/ (in-process primitives): edge owns only the proximity/location/disconnection concerns that arise at the network edge — performance's locality is algorithmic, edge's locality is geographic (C4). 10 P-rules, broad derivation (7 C-rules: C1, C3, C4, C5, C6, C7, C8). Depends on core/. Cross-links are one-directional outward (D-026 extended): performance/frontend (P6 geographic cache invalidation vs generic caching), performance/P4 (P3 constrained-device vs generic resource bounds), observability/metrics + observability/logging (P10 local-first telemetry), concurrency/patterns (P5 offline write-queue analog), security/secrets (P9 device identity), security/input-validation (P6 cache poisoning), data/migrations (P4 schema migration under sync). Edge↔messaging intra-v0.4 cross-links resolve bidirectionally in P5 (ATELIER-114, IDEATE-40): edge/iot.md → messaging/queues (MQTT QoS parallels to delivery semantics). Derived docs: cdn.md, offline-first.md, iot.md, sync.md.

• messaging/ — cross-process messaging domain. Owns the cross-process/network-failure-model angle (D-062): messages as contracts, explicit delivery semantics, idempotent consumers, bounded backpressure, observable lag. Boundary vs concurrency/ (in-process/crash-failure-model): messaging's queue fails by network partition/broker restart/consumer crash-and-retry; concurrency's queue fails by OOM or thread crash. The discriminator is the failure model (D-062). 10 P-rules, broad derivation (7 C-rules: C1, C2, C4, C5, C6, C7, C8). Depends on core/. Cross-links are one-directional outward (D-026 extended): concurrency/patterns (P6 broker-backed bounded queue vs in-process Pattern 5; P3 cross-process idempotent retry vs in-process retry), observability/metrics + observability/tracing (P10 broker signals), data/schema-design (P1/P9 message schema evolution), errors/patterns (P5 errors as data for poison messages), edge/iot (P4 — bidirectional resolution of the MQTT QoS cross-link per IDEATE-40). Derived docs: queues.md, pubsub.md, streams.md, delivery-semantics.md.

v0.4 Language-Derived Extension

The languages/ tree extends from a first-principles-only stub (v0.1) to a full derived-doc tree (v0.4). Each of the 4 v0.1 stubs (typescript.md, python.md, go.md, rust.md) is extended with a pointer to its 4 derived docs (16 total). Language-derived docs apply, not derive domain principles (D-063): they introduce no new P-rules and no new matrix rows (D-066). Every section header names the traced core C-rule(s) AND the traced domain P-rule(s) inline (e.g., ## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity)). The first-principles stubs retain their existing section structure — no P1–P10 numbering is added to languages (D-063); languages are an application lens, not a principle source, preserving the core > domains > languages ordering ("conflicts go UP, never sideways").

The matrix/principles-matrix.md gains no language rows — it stays at 190 P-rules / 19 domains (D-066). Language-derived-doc traceability is captured in a new ## Languages Coverage sub-table in matrix/domain-coverage.md (exactly 16 rows, one per derived doc) — the verifiable aggregate; inline section-headers are the per-doc detail. Every derived doc traces to ≥1 domain P-rule (D-066, no orphans).

Derived docs by language:

• TypeScript — ts-types.md, ts-tooling.md, ts-async.md, ts-testing.md
• Python — py-types.md, py-tooling.md, py-async.md, py-testing.md
• Go — go-types.md, go-tooling.md, go-concurrency.md, go-testing.md
• Rust — rs-ownership.md, rs-tooling.md, rs-async.md, rs-testing.md

The manifest (MANIFEST.md) is extended with a new ## Languages section (D-065) listing the 4 v0.1 stubs (closing pre-existing drift parallel to the v0.2 ESC-002 / ATELIER-91 precedent) and the 16 new v0.4 derived docs. The review/ docs (agent-checklist, peer-review-checklist, anti-patterns) gain edge, messaging, and language-derived trigger sections. Examples (P5) are illustrative markdown with fenced code only — no standalone .ts/.py/.go/.rs runtime artifacts (D-020 docs-only contract, extended in v0.4 to language-derived-doc artifact types).

See .ciagent/atelier/RESEARCH-v0.4.md for the full prior-art survey (Akamai/Cloudflare, Kafka/RabbitMQ/NATS, Jepsen, Reactive Streams, CloudEvents, CRDTs, PouchDB, MQTT/CoAP) and .ciagent/atelier/PERSONAS.md for the v0.4 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific edge-engineer, languages-engineer).