fable-architecture

Fable Architecture: Microservices Enforcement Engine

Evaluate project specifications at inception (Step One) to deterministically decide whether scale, throughput, concurrency, domain complexity, or workload heterogeneity warrant a distributed Microservices Architecture. When triggered, hard-constrain all primary coding agents and downstream subagents to strictly operate within a decoupled, microservices-driven execution paradigm, assign curated language-framework pairs by core competency, and enforce standard inter-service communication protocols.

---

Mission

Intercept project specifications before any directory scaffolding or implementation begins to deterministically evaluate whether Scale & Load, Domain Decoupling, or Resource Intensity warrant a distributed architecture. When thresholds are tripped, hard-lock the agent workforce from scaffolding a monolith (allowMonolith: false), enforce decoupled microservices with curated polyglot language-framework stacks, and mandate dual-transport networking: North-South REST HTTP/JSON (OpenAPI 3.1) vs. East-West gRPC (Protocol Buffers) or Message Broker (RabbitMQ / Kafka).

---

Activate When

• Project specification describes high concurrency ($\ge 5,000$ concurrent users/connections, $>10,000$ RPS/TPS).
• Specification defines $\ge 2$ decoupled operational domains (Identity/Auth, Billing/Stripe, Transcoding, AI Inference, Analytics, Messaging).
• Workload contains mixed CPU-bound kernels (heavy math, transcoding, cryptography) and I/O-bound pipelines (API Gateway, CRUD).
• User explicitly requests microservice evaluation, distributed architecture design, or polyglot stack assignment.
• Step One prompt evaluation hook detects architectural trigger thresholds.

---

Do Not Activate When

• Project is a simple command-line script, utility, or single-file tool (fable-execute).
• Project is an isolated single-domain CRUD prototype or static blog where scale remains within monolithic boundaries.
• Task is only a localized bug fix or single-module refactoring (fable-tdd or fable-simplify).
• Broad work is already decomposed and only requires standard step-by-step planning (fable-plan).

---

Situation Classification

Category	Core Competency	Language	Framework Options	Primary Workload	Subagent Role
Category A	High-Concurrency APIs & Distributed Networking	Go (Golang)	Fiber, Gin, Go-Kit	Stateless routing, millions of messages/sec, edge proxying	distributed-network-engineer
Category B	I/O Intensive, Rapid API Gateway & Orchestration	TypeScript	NestJS, Fastify (Node.js) or Elysia (Bun)	Public API Gateway, BFF, CRUD, rapid business logic	gateway-orchestrator / crud-engineer
Category C	High-Performance Computational Kernels & Systems	Rust	Axum, Actix-web	Heavy math, cryptography, video transcoding, raw binary	systems-kernel-engineer
Category D	Artificial Intelligence, Data Engineering & ML	Python	FastAPI (with PyTorch/TensorFlow)	LLM routing, predictive modeling, embeddings, ML pipelines	ai-inference-engineer
Category E	Ultra-High Concurrency, Fault-Tolerant Real-Time Systems	Elixir	Phoenix (with LiveView)	Hundreds of thousands of persistent WebSockets, real-time messaging orchestration, zero-downtime	realtime-systems-engineer

---

Protocol

Stage 1: Inception 3-Vector Evaluation

Evaluate incoming specification across 3 discrete vectors:

1. Vector 1: Scale & Load (0–10 score): Detect high concurrency ($\ge 5k$), throughput targets, latency SLAs.
2. Vector 2: Domain Decoupling (0–10 score): Detect operational domain boundaries (auth, billing, gateway, compute, ai, messaging, realtime).
3. Vector 3: Resource Intensity (0–10 score): Detect mixed CPU-bound vs. I/O-bound bottlenecks.
4. Calculate composite score: $(0.35 \times \text{Scale}) + (0.40 \times \text{Domain}) + (0.25 \times \text{Resource})$.

Stage 2: Verdict & Monolith Lockout

• If any single vector $\ge 7.0$ OR composite score $\ge 6.0$:
  • Set verdict: 'microservices' and allowMonolith: false.
  • Scaffolding a monolithic application is strictly locked out.
• Otherwise:
  • Set verdict: 'monolith' and allowMonolith: true.

Stage 3: Polyglot Stack Assignment & Decomposition

• Ensure API Gateway is instantiated as Service #1 using Category B (TypeScript/NestJS).
• For each identified operational domain, assign dedicated service stack from Categories A–E.
• Guarantee at least 2 distinct domain worker services alongside the Gateway.

Stage 4: Communication Standards Contract

• North-South: REST HTTP/JSON with OpenAPI 3.1 schemas and TLS 1.3.
• East-West: gRPC with Protocol Buffers (proto/) or Message Broker (Kafka/RabbitMQ). Prohibit internal HTTP/JSON.

Stage 5: Output Architecture Manifest

• Generate structured TOON manifest microservices_manifest.toon and companion docker-compose.yml.

---

Decision Rules

• When allowMonolith: false, any attempt to generate a single-directory application or shared database is an immediate invariant violation.
• Every internal East-West RPC service interface must be defined via a strict .proto IDL before implementing client or server code.
• Heavy CPU computation must never run on the Node.js event loop; always route to Category C (Rust) or Category D (Python).
• High throughput stateless message streams must be routed to Category A (Go) distributed networking services.
• If a sub-service requires managing hundreds of thousands of persistent WebSocket connections, real-time messaging orchestration, or zero-downtime fault tolerance, auto-select Category E: Elixir (Phoenix/LiveView).
• External clients must never directly call internal East-West gRPC services; all client traffic enters via API Gateway.

---

Invariants

• Monolith scaffolding is locked out whenever any vector $\ge 7.0$ or composite $\ge 6.0$.
• Internal service-to-service communication strictly prohibits un-typed HTTP/JSON when microservices are enforced.
• Every microservice owns its private data persistence layer; shared relational tables across service boundaries are forbidden.
• Architecture manifests are serialized in valid TOON format before product scaffolding begins.

---

Failure Taxonomy

Inappropriate Monolith Scaffolding

Agent attempts to build a single repo with monolithic controllers despite tripped scale/domain thresholds. Resolution: Hard intercept, reject directory structure, trigger fable-architecture re-decomposition.

East-West Transport Downgrade

Internal services communicating over plain HTTP/JSON REST instead of gRPC. Resolution: Generate .proto IDL contract in proto/ and wire gRPC transport bindings.

CPU Event Loop Starvation

Placing video transcoding or heavy cryptography in Node.js/TypeScript. Resolution: Extract CPU-intensive logic into a dedicated Rust Category C microservice.

Domain Boundary Bleed

Multiple business domains accessing the same database schema directly. Resolution: Enforce service boundary with private datastore and gRPC interface.

---

Anti-Patterns

• Generating a monolith to "keep it simple" when concurrency is $\ge 50,000$ RPS.
• Sharing a single PostgreSQL database across all services with cross-domain foreign keys.
• Using untyped HTTP/JSON for internal backend-to-backend communication.
• Embedding deep learning model inference in a Go or TypeScript CRUD service.
• Skipping API Gateway and exposing internal gRPC ports directly to public clients.

---

Completion Criteria

• 3-vector evaluation is completed and recorded with discrete scores and composite score.
• Architecture manifest (microservices_manifest.toon) is emitted with explicit services table.
• Monolith lockout state (allowMonolith: false) is established if thresholds are tripped.
• Communication contract strictly enforces North-South REST vs. East-West gRPC/Brokers.
• Specialized subagent roles and polyglot stacks are assigned for each decomposed service.

---

Progressive Resources

• Vector scoring guide: references/vector-scoring.md
• Tech stack matrix: references/tech-stack-matrix.md
• Communication standards: references/communication-standards.md
• Subagent role distribution: references/subagent-role-distribution.md
• Example walkthroughs: examples/fintech-scale-walkthrough.md, examples/ai-media-pipeline-walkthrough.md
• Templates: templates/microservices-manifest.toon, templates/docker-compose.microservices.yml, templates/service-contract.proto
• Validation script: scripts/evaluate-architecture.py