architecture-advisor

name	architecture-advisor
description	Evidence-based architecture guidance grounded in 142 production codebases and 17 production system case studies. Reviews project goals, examines the user's codebase, and provides data-driven recommendations for architecture style selection, quality attribute trade-offs, and pattern validation. Use when the user asks "which architecture should I use", "is my architecture right for this", "architecture review", "help me choose between X and Y", "what patterns work for my domain", "architecture trade-offs", "validate my architecture", or any question about choosing, evaluating, or improving software architecture. Also triggers on "architecture patterns", "quality attributes", "ADR examples", "feasibility analysis", "fitness functions", or "kata preparation".
license	MIT
allowed-tools	Bash, Read, Grep, Glob, Agent
metadata	{"short-description":"Production-evidence-based architecture guidance from 142 codebases","version":"4.0.0","author":"cristos","source-repo":"https://github.com/cristoslc/architecture-reference"}

Architecture Advisor

Evidence-based architecture guidance grounded in production reality. Every recommendation cites real systems, not opinion or convention.

The evidence hierarchy:

1. Discovered production repos (142 entries) — primary statistical baseline. What production codebases actually use.
2. AOSA/RealWorld production systems (17 entries) — deep case studies from system creators. Highest per-system authority.
3. KataLog competition (78 teams) — qualitative annotation. Never-built designs valued for ADR reasoning, judge commentary, and cost projections. Not primary evidence.
4. Reference implementations (50 entries) — teaching examples. Not counted in frequency rankings.

Reference Data

All reference data ships with the skill in references/:

• references/catalogs/ — YAML catalog entries per source (Discovered, AOSA, RealWorldASPNET, TheKataLog, ReferenceArchitectures)
• references/analysis/ — Source analysis documents
• references/reference-library/ — Decision navigator, glossary, evidence summaries, problem-solution matrix
• references/templates/ — ADR, feasibility, fitness functions, C4, and kata guides
• references/style-taxonomy.yaml — Canonical style definitions

When a specific production project is relevant to the user's question, point them to the project's repository directly rather than summarizing second-hand — the catalog entry's source_url field has the link.

The offline reference at the bottom of this file provides summary statistics for quick answers without reading the full catalog.

What This Skill Does

The user brings an architecture problem. You research the evidence base and provide data-driven guidance with citations.

Step 1: Understand the problem

Ask enough to classify the situation:

• Style selection: "Which architecture fits my project?" → consult production frequency data and domain-style correlations
• Architecture review: "Is my current architecture sound?" → examine their codebase and compare to evidence
• Pattern trade-offs: "Microservices vs Service-Based?" → compare production evidence for both
• Quality attributes: "How do I get scalability AND simplicity?" → consult QA evidence and trade-off data
• Domain mapping: "What works for e-commerce/healthcare/etc?" → consult domain-style correlations
• Kata preparation: "Help me prepare for an architecture kata" → use templates and competition insights

Context Detection

After initial classification, determine whether the user's concern is application-centric, platform-centric, or hybrid. This classification is internal — do not announce it to the user. It can be revised mid-conversation as new information emerges.

Use the signal taxonomy below to classify the context based on the user's language and concerns:

Signal	Platform indicators	Application indicators
Scope language	"services", "repos", "components", "ecosystem"	"my codebase", "the app", "our monolith"
Boundary concerns	"API contracts", "shared schemas", "protocol specs"	"module boundaries", "package organization", "layers"
Deployment	"deploy independently", "multiple pipelines"	"single deployment", "CI/CD pipeline"
Communication	"HTTP/gRPC between services", "message queues"	"function calls", "dependency injection"
Team structure	"multiple teams own different services"	"our team", "the frontend/backend"

When signals are mixed, use lightweight probing questions to disambiguate:

1. "Are you thinking about the architecture of a single codebase, or how multiple independently-deployed services fit together?" — distinguishes application from platform
2. "Do the components you're describing share a deployment pipeline, or does each have its own?" — deployment topology is the strongest differentiator
3. "Are the boundaries you're concerned about within a single repo or across repos owned by different teams?" — ownership model reveals scale

Context gating for subsequent steps:

• Application context → Steps 3-5 use single-repo evidence, existing Q1-Q8 classification, and paths A-J
• Platform context → Steps 3-5 use ecosystem evidence, P1-P6 classification, and paths P-A through P-D
• Hybrid context → Steps 3-5 merge both evidence pools with clear provenance labels; offer the user a choice of which classification questions to answer, or answer both sets

Step 2: Examine the codebase (if available)

If the user has a codebase to evaluate, examine it before giving advice. Read actual code — understand their current architecture before recommending changes. Use the discover-architecture skill's approach: read entrypoints, module boundaries, communication patterns, dependency direction, and deployment configs (compose files, proxy configs, k8s manifests) that may introduce components, boundaries, or contracts invisible in application code.

Step 3: Research the evidence

Research priorities depend on the context detected in Step 1.

Application context (default)

For style selection or trade-off questions, consult in this order:

Priority	Source	Path (references/)	What it answers
1	Discovered frequency rankings	reference-library/solution-spaces.md	"How common is this style in production?"
2	Domain-style correlations	reference-library/problem-solution-matrix.md	"What styles work for my domain?"
3	Decision navigator (Q1-Q8, paths A-J)	reference-library/decision-navigator.md	"Given my constraints, what's recommended?"
4	Production system narratives	catalogs/AOSA/, catalogs/RealWorldASPNET/	"How did real systems implement this?"
5	Style evidence details	reference-library/evidence/by-architecture-style.md	"What's the full evidence picture for this style?"
6	Competition team reasoning	catalogs/TheKataLog/	"Why did teams choose this? What trade-offs did they document?"

Platform context

For platform/ecosystem architecture questions, consult in this order:

Priority	Source	Path (references/)	What it answers
1	Ecosystem frequency rankings	reference-library/evidence/by-architecture-style.md (ecosystem section)	"How common is this style across ecosystems?"
2	Ecosystem catalog entries	catalogs/Discovered/docs/catalog/ (entries with scope: ecosystem)	"What composition patterns do real ecosystems use?"
3	Decision navigator (P1-P6, paths P-A through P-D)	reference-library/decision-navigator.md	"Given my platform constraints, what's recommended?"
4	Single-repo entries exemplifying member-service patterns	catalogs/Discovered/docs/catalog/ (entries from ecosystem member repos)	"How do individual services within ecosystems architect themselves?"
5	Production system narratives	catalogs/AOSA/, catalogs/RealWorldASPNET/	"How did real platform systems implement this?"
6	Competition team reasoning	catalogs/TheKataLog/	"What platform-scale reasoning did teams document?"

Hybrid context

When the user's concern spans both scales, merge application and platform pools. For each piece of evidence cited, label its provenance:

• (single-repo) for evidence from the 142 individual production repos
• (ecosystem) for evidence from the 11 ecosystem entries
• (production system) for AOSA/RealWorld case studies

This lets the user see which scale each recommendation draws from.

Quality attribute questions (all contexts)

Priority	Source	Path
1	QA detection data	reference-library/evidence/by-quality-attribute.md
2	Cross-source QA analysis	reference-library/evidence/cross-source-analysis.md

Meta-practice questions (all contexts)

Priority	Source	Path
1	Templates	templates/adr-guide.md, templates/feasibility-guide.md, templates/fitness-functions-guide.md
2	Competition evidence	KataLog team submissions (these are KataLog's genuine strength — meta-practices documented in team ADRs)

Step 4: Synthesize with citations

Every recommendation MUST cite specific evidence:

• Production frequency: "Microkernel appears in 83 of 142 production repos (58.5%)" — cite Discovered data
• Production depth: "NGINX uses event-driven architecture for non-blocking I/O (AOSA)" — cite specific systems
• Domain correlation: "In Developer Tools repos, Microkernel (61%) and Layered (47%) dominate" — cite domain data
• Platform vs application: "Microservices skews heavily toward platforms (13%) vs applications (2%)" — cite split data
• Qualitative reasoning: "KataLog teams explain that cost/feasibility analysis is the #1 predictor of placement (4.5x likelihood)" — cite as annotation, not primary evidence
• Ecosystem evidence: "The ELK Stack ecosystem uses Pipeline + Event-Driven composition (Discovered ecosystem catalog)" — cite ecosystem entries specifically
• Composition patterns: "Service-Based hub-and-spoke integration, as seen in the *arr Media Stack" — cite composition_pattern fields from ecosystem catalog entries

Do not make unsupported claims. If evidence is thin (small sample, single source), say so.

Step 5: Give actionable guidance

Don't just report data — help the user make a decision:

• Recommend specific styles with evidence-backed reasoning
• Flag risks and trade-offs with production evidence
• Suggest concrete next steps (ADRs to write, patterns to prototype, quality attributes to prioritize)
• If examining their codebase, identify gaps between current architecture and evidence-backed patterns

Step 6: Save report (optional)

When the user asks to save the report ("save this", "write a report", "save to docs"), or when the analysis was a full architecture review (not just a quick question), offer to persist the output:

1. Create the output directory if needed: mkdir -p docs/architecture-reports/
2. Generate the report following the template in references/report.template.j2 — the template defines the frontmatter fields, section order, and required content. You don't need a Jinja2 renderer; just fill in the structure by hand using the template as a guide.
3. Save as docs/architecture-reports/<project-name>-<YYYY-MM-DD>.md
4. If a report for the same project and date already exists, append a sequence suffix: -2, -3, etc.

The report template includes YAML frontmatter (project, date, scope, styles) so reports are machine-parseable for future cross-project analysis.

Don't save reports for casual Q&A ("what's the most common style?"). Save when there's a concrete analysis tied to a specific project or codebase.

Glossary

For definitions of all 12 architecture styles, 13 quality attributes, evidence sources, and key terms, read references/reference-library/glossary.md (or the offline reference below).

Offline Reference

When no synced data is available, use these findings. All data from production-only frequency recomputation (142 entries, deep-analysis validated).

Production frequency rankings (Discovered, 142 production repos)

Rank	Style	Count	%	Platform	Application	Production Systems
1	Microkernel	83	58.5%	61%	55%	LLVM, SQLAlchemy, GStreamer, Jellyfin, Orchard Core, nopCommerce
2	Layered	78	54.9%	47%	67%	nopCommerce
3	Modular Monolith	57	40.1%	41%	38%	Orchard Core
4	Event-Driven	17	12.0%	8%	18%	NGINX, Twisted, ZeroMQ, Squidex, Bitwarden
5	Pipeline	13	9.2%	13%	4%	NGINX, LLVM, ZeroMQ, Graphite, GStreamer, Jellyfin
6	Microservices	12	8.5%	13%	2%	(none in evidence base)
7	Service-Based	7	4.9%	5%	5%	Selenium, Graphite, Bitwarden
8	Hexagonal	5	3.5%	3%	4%	(none)
9	DDD	3	2.1%	2%	2%	(none)
10	Multi-Agent	1	0.7%	0%	2%	(none)
11	Space-Based	1	0.7%	1%	0%	Riak
12	CQRS	1	0.7%	0%	2%	Squidex

Dataset: 184 repos total (142 production + 42 reference). 87 platforms, 55 applications, 1.58:1 ratio. Zero Indeterminate (deep-analysis validated). 74% of repos exhibit exactly 2 styles.

Ecosystem frequency rankings (11 ecosystem entries)

Rank	Style	Count	%	Example ecosystems
1	Service-Based	5	45%	*arr Media Stack, Grafana LGTM, HashiCorp, Fediverse, Temporal
2	Microservices	3	27%	Istio/Envoy, Sentry, Supabase
3	Pipeline	2	18%	ELK Stack, Apache Data Ecosystem
4	Event-Driven	1	9%	Apache Data Ecosystem (secondary)
5	Space-Based	1	9%	Apache Data Grid

Key insight: Service-Based dominates ecosystem evidence (45%) despite ranking 7th in single-repo frequency (4.9%). Many real-world Service-Based systems are ecosystems of independent repos.

Key findings from production evidence

1. Microkernel and Layered dominate. The top 3 styles (Microkernel, Layered, Modular Monolith) appear in 40-59% of production repos. Everything else is below 12%.

2. The proposal-production gap. What competition teams propose diverges from what exists in production. Microservices: 50% of teams, 8.5% of repos. Pipeline: 0% of teams, 9.2% of repos. Layered: 0% of teams, 54.9% of repos.

3. Tutorial bias inflated DDD, CQRS, Hexagonal. Prior methodology counted reference implementations alongside production: DDD was 17.8% (now 2.1%), CQRS was 10.4% (now 0.7%). These patterns are well-documented in teaching materials but rare in production.

4. Platform vs application architecture differs. Microservices is almost exclusively a platform pattern (13% vs 2%). Layered skews toward applications (67% vs 47%). Event-Driven skews toward applications (18% vs 8%).

5. Multi-style composition is normal. 74% of repos exhibit 2 styles. The most common combinations: Microkernel + Layered, Microkernel + Modular Monolith, Layered + Modular Monolith.

Quality attribute detection (142 production repos)

QA	Detected	%	Reliability
Deployability	126	88.7%	Inflated — Docker is universal
Modularity	38	26.8%	Moderate
Scalability	33	23.2%	Moderate
Fault Tolerance	20	14.1%	Moderate
Observability	5	3.5%	Underdetected
Evolvability	3	2.1%	Severely underdetected
Performance, Security, Testability, etc.	0	0%	Invisible in code

Detection bias: Code analysis reliably detects QAs with filesystem signals (Docker, CI configs, module boundaries) but cannot detect Performance, Security, Testability, or Cost concerns. Competition evidence (KataLog) fills this gap — teams documented these invisible concerns in ADRs and presentations.

Competition insights (KataLog — qualitative annotation, not primary evidence)

Meta-architectural practices that predict competition success:

• Feasibility analysis: 4.5x more likely to place top-2 (75.6% of teams skip it)
• ADR discipline: Winners average 15.0 ADRs vs 8.5 for runners-up
• Fitness functions: 55% of winners include them vs ~17% overall
• Multi-style composition: 73% of winners use 2+ styles
• The Scalability Trap: Winners cite scalability LESS often (55%) than runners-up (68%)

These practices are KataLog's genuine contribution — meta-architectural reasoning unavailable in production code analysis.

Domain coverage (47 unique domains in Discovered)

Top domains: Developer Tools (36), E-Commerce (15), Observability (11), Data Processing (11), Infrastructure (9), Data Grid (8), Messaging (6), Productivity (5), Media Automation (5), Workflow Orchestration (5).

Evidence source summary

Source	Entries	Role	Value
Discovered (production)	142	Primary statistical baseline	Largest, most diverse corpus of real production code
AOSA	12	Production depth	Case studies written by system creators (NGINX, HDFS, Git, etc.)
RealWorldASPNET	5	Production depth	Modern .NET apps with real users
KataLog	78	Qualitative annotation	ADR reasoning, judge commentary, cost projections
RefArch + Discovered ref	50	Teaching examples	Concrete code examples; zero weight in rankings