Discover Architecture

Discover Architecture

Analyze a codebase to identify its architecture style(s) by reading actual source code — not by counting filesystem signals or matching directory name patterns. Architecture is about structure and relationships: how modules communicate, where boundaries are enforced, what the dependency graph looks like. These things require reading code, not scanning for Dockerfiles.

The 12 Canonical Styles

These are the only valid architecture style classifications. Read references/styles.md for full definitions, distinguishing characteristics, and production frequency data.

How to Classify

Step 1: Inventory the codebase

Get oriented quickly. Run these in parallel:

• ls the root directory and key subdirectories (src/, lib/, packages/, services/, internal/, cmd/)
• Read README.md (first 200 lines) — often states what the project IS
• Read any ARCHITECTURE.md, docs/architecture/, or CONTRIBUTING.md
• Check package metadata (package.json description, pyproject.toml, pom.xml, Cargo.toml, go.mod)
• Note the primary language(s) and framework(s)

Step 2: Inspect code structure

This is where classification happens. Read actual source files — not just directory names.

For each candidate style, look for structural evidence:

• Module boundaries: How is code organized? Are there clear module interfaces, or is everything in one flat namespace?
• Dependency direction: Do dependencies flow in one direction? Is there dependency inversion?
• Communication patterns: How do components talk to each other? Direct function calls? Message passing? HTTP? Events?
• Extension mechanisms: Are there plugin registries, middleware chains, hook systems?
• Data flow: Does data flow through transformation stages, or is it request/response through layers?
• Deployment topology: Is this one deployable unit or many? How do you tell?

Read at least:

• 2-3 "entrypoint" files (main.go, app.py, Program.cs, index.ts, etc.)
• The dependency injection / wiring configuration (if any)
• 2-3 representative domain files showing the core architecture
• Any inter-module or inter-service communication code

Step 3: Classify with evidence

Based on what you read, determine:

1. Primary style(s) — the dominant architectural pattern(s). Most production repos exhibit 2 styles (74% in the evidence base). 2. Confidence — how clear the evidence is (0.0-1.0) 3. Evidence citations — specific files, classes, and patterns that support each classification

Classification principles:

• Classify what the repo IS, not what it enables. A plugin framework IS Microkernel. A message broker IS Event-Driven infrastructure.
• Multi-style composition is normal. Don't force single-style classification. A system can be both Layered and Microkernel (layered internal structure with plugin extension).
• Code trumps documentation. If the README says "microservices" but the code is a monolith with a single database, classify based on code.
• Distinguish style from technology. Having Docker doesn't make it Microservices. Having Kafka doesn't make it Event-Driven. Look at how the architecture is actually structured.
• If truly indeterminate, say so and explain why. Don't guess.

Step 4: Determine scope and use-type

Scope (per ADR-001):

• Platform: designed to be extended/built upon — plugin systems, API surfaces, infrastructure for other software (e.g., Kafka, Grafana, VS Code)
• Application: end-user facing, solves a specific problem (e.g., Mastodon, Ghostfolio)

Use-type (per ADR-001):

• Production: real system used in production or production-ready
• Reference: educational, demo, template, starter kit

Step 5: Identify quality attributes

Only report quality attributes with direct evidence in code:

Do NOT report quality attributes you can't see in code (Performance, Security, Testability, etc.) — these are real but invisible in source analysis. Note this limitation in the report.

Step 6: Infer domain

From README, package metadata, directory naming, and code content. Use specific domains when clear (E-Commerce, Developer Tools, Observability, etc.). Use "General Purpose" if unclear.

Output Format

Produce a markdown report:

# Architecture Analysis: <project name>

**Scope:** platform | application
**Use-type:** production | reference
**Primary language:** <language>
**Confidence:** <0.0-1.0>

## Architecture Styles

### <Style 1> (primary)

<2-3 sentences explaining WHY this classification, citing specific files and patterns>

### <Style 2> (secondary)

<Same format>

## Evidence Summary

| Style | Confidence | Key Evidence |
|-------|-----------|-------------|
| <style> | <0.0-1.0> | <specific files, patterns, classes cited> |

## Quality Attributes Detected

- **<QA>**: <evidence> (e.g., "Deployability: Dockerfile, GitHub Actions CI, Helm charts")

> **Detection limitation:** Quality attributes like Performance, Security, and Testability are architecturally significant but invisible in source code analysis.

## Domain

<domain> — <brief justification>

## Production Context

<How this repo's architecture compares to production evidence:>
- <Style> appears in N% of 142 production repos in the evidence base
- <Any notable patterns: "Microkernel + Layered is the most common combination">
- <Platform/application context if relevant>

If the user wants YAML catalog output (for the evidence base), also produce a YAML entry per the schema in references/catalog-schema.yaml.

The report structure follows the template at references/report.template.j2. When saving reports, use docs/architecture-reports/<project-name>-<YYYY-MM-DD>.md.

Edge Cases

Monorepo with multiple projects: Note the monorepo structure. Classify the overall architecture, noting sub-projects if they have distinct styles.

Trivial repos (< 10 source files): Classification may not be meaningful. Say so.

Libraries/frameworks (consumed as dependencies, not deployed): These have no deployable architecture. Classify as what they ARE (a plugin framework is Microkernel), note they're libraries.

Indeterminate: If code is too flat, too small, or too unconventional to classify, say "Indeterminate" and explain what would help (more code, clearer boundaries, etc.).

Architecture Style Reference

Production frequency data from 142 production repos (SPEC-022 deep-analysis, ADR-002). Use this context to inform classifications — knowing what's common vs rare helps calibrate confidence.

Production Frequency Rankings

74% of production repos exhibit exactly 2 styles. Multi-style composition is normal.

Style Definitions

Microkernel (Plugin Architecture)

A host application with extension points through which independently deployable plugins extend core functionality. The core provides lifecycle management, configuration, and shared services. Plugins provide domain-specific behavior and can be added, removed, or replaced without modifying the core.

Distinguishing signals in code:

• Plugin/extension registries or loaders
• Extension point interfaces or contracts
• Dynamic module loading or hot-reloading
• Host/plugin separation in directory structure
• Configuration-driven feature activation

Common confusion: Having configurable components doesn't make something Microkernel. Look for explicit extension points designed for third-party or unknown-at-build-time plugins.

Examples: VS Code (extensions), WordPress (plugins), n8n (nodes), Grafana (panels/datasources), ESLint (rules/plugins)

Layered Architecture (N-Tier)

Horizontal separation into layers (typically presentation, business logic, data access), where each layer depends only on the layer below. Enforces strict dependency direction.

Distinguishing signals in code:

• Layer-named directories (controllers/, services/, repositories/, models/)
• Clear dependency flow: upper layers import from lower, never reverse
• Service/repository pattern separating business logic from data access
• Request flows down through layers and responses flow back up

Common confusion with Pipeline: Layered is about separating concerns by responsibility type (all UI here, all business logic there). Pipeline is about data transformation through stages. In Layered, every request goes through the same layers. In Pipeline, data flows forward through processing steps.

Modular Monolith

Single deployable unit organized into well-defined, cohesive modules with clear boundaries. Modules are logically independent but share process, memory, and deployment.

Distinguishing signals in code:

• Module-per-directory structure with clear APIs between modules
• Module registries or feature management
• Internal module interfaces (not just folders, but actual boundary enforcement)
• Single deployment artifact (one Dockerfile, one deploy script)
• Feature toggles enabling/disabling entire modules

Common confusion with Layered: Layered separates by concern type (presentation/business/data). Modular Monolith separates by domain (orders module, users module, billing module). A system can be both.

Event-Driven Architecture

Components communicate through events rather than direct synchronous calls. Producers emit events without knowledge of consumers.

Distinguishing signals in code:

• Message broker configuration (Kafka, RabbitMQ, NATS, Redis pub/sub)
• Event bus implementations (in-process or distributed)
• Event handler registrations
• Async message processing patterns
• Event schemas (Avro, Protobuf, AsyncAPI)

Common confusion: Having a message queue doesn't automatically make the ARCHITECTURE event-driven. Look at whether events are the PRIMARY communication mechanism or just used for one specific integration.

Note: Event-Driven means different things in different contexts: event-loop concurrency (NGINX), event sourcing as data model (Squidex), message-based integration (most common in code), or pub/sub communication.

Pipeline (Pipe-and-Filter)

Data flows through ordered processing stages where each stage transforms input to output. Stages are independent, composable, and often stateless.

Distinguishing signals in code:

• Middleware chains or filter pipelines
• Stage-based processing with clear input/output contracts
• Data transformation chains
• Compiler/transpiler pass architectures
• ETL or data processing workflows

Common confusion with Layered: Pipeline is about data flowing FORWARD through transformation stages. Layered is about request/response flowing DOWN through concern layers. Pipeline stages are composable and can be rearranged; layers are fixed structural boundaries.

Microservices

Independent, loosely coupled services deployed, scaled, and developed independently. Each service owns its data and communicates via APIs or messaging.

Distinguishing signals in code:

• Multiple independently deployable services (separate Dockerfiles, separate CI/CD)
• Per-service databases or data stores
• API gateway or service mesh configuration
• Inter-service communication code (HTTP clients, gRPC, message passing)
• Independent versioning per service

Common confusion with Service-Based: Microservices have full independence (own database, own deployment, own team ownership). Service-Based shares infrastructure (shared database, coordinated deployment).

Service-Based Architecture

Coarse-grained service decomposition with shared infrastructure. Less distributed than microservices.

Distinguishing signals in code:

• Multiple services sharing a database
• Coarse service boundaries (fewer, larger services)
• Simple inter-service communication (direct HTTP, shared message bus)
• Coordinated deployment (single docker-compose, shared CI/CD)

Hexagonal Architecture (Ports and Adapters, Clean Architecture)

Core business logic isolated with dependencies pointing inward. External concerns connect through ports (interfaces) and adapters (implementations).

Distinguishing signals in code:

• Port interfaces in the domain/application layer
• Adapter implementations in infrastructure layer
• Domain layer with ZERO external imports (no database, no HTTP, no framework)
• Explicit dependency inversion at module boundaries

Common confusion with Microkernel: Hexagonal is about dependency direction (keeping domain pure). Microkernel is about runtime extensibility (adding unknown future capabilities). A Hexagonal system has no plugin system. A Microkernel system may have terrible internal dependency management.

Domain-Driven Design

Code organized around business domains using bounded contexts, aggregates, domain events, and ubiquitous language.

Distinguishing signals in code:

• Bounded context directories or packages
• Aggregate root patterns
• Domain event implementations
• Repository pattern (domain-specific, not generic ORM)
• Value objects and entities with behavior (not anemic models)

Note: DDD production frequency is very low (2.1%). It is far more common in tutorials and reference implementations than in production code. Be cautious about classifying based on directory names alone — many repos have a domain/ folder without practicing DDD.

Multi-Agent

Multiple autonomous agents with specialized capabilities collaborating through coordination protocols.

Distinguishing signals in code:

• Agent role definitions and specialization
• Multi-agent coordination (supervisor, orchestrator, swarm)
• Tool-use registries
• Agent-to-agent communication protocols

Space-Based Architecture

In-memory distributed data grid with peer-to-peer replication and no central database.

Distinguishing signals in code:

• Distributed in-memory data structures
• Consistent hashing implementations
• Masterless replication protocols
• Eventual consistency mechanisms

CQRS (Command Query Responsibility Segregation)

Separate read and write models. Commands modify state; queries operate on read-optimized projections.

Distinguishing signals in code:

• Explicit command and query separation (separate classes, handlers)
• Event store implementations
• Projection/read-model builders
• Separate write and read database configurations

Note: CQRS production frequency is very low (0.7%). Commonly seen in tutorials but rare in production. Be cautious.