The Architecture Council

An AI-powered Software Architecture Design Authority where specialised AI agents evaluate architecture decisions and codebases, producing scored reviews with reasoned rulings.

Overview

The Architecture Council creates a visual panel of AI agents — each powered by a different LLM — that analyse software architecture decisions and codebases, producing consensus-based rulings. Agents evaluate proposals against standards, community health, strategic alignment, and security implications, synthesising diverse perspectives into actionable guidance.

Like having a design authority board available 24/7 in under 60 seconds.

Two Modes

ADR Review

Submit an Architecture Decision Record proposal. Four specialist agents evaluate in parallel, the DA Chair synthesises, and you get a structured APPROVED / CONDITIONAL / REJECTED / DEFERRED ruling with scored findings.

Codebase Review

Point the council at any public GitHub repository. The system clones it, indexes it, and runs the full panel against the actual code — scanning for secrets, analysing imports, reviewing standards compliance, and assessing DX. Results are exported as a full markdown report.

The Council Panel

Agent	LLM	Role	Notes
Standards Analyst	OpenAI GPT-4.1	Code structure, naming, dependency health, linting	Uses FileReader + PatternCheck tools
DX Analyst	Perplexity Sonar Pro	README, docs, test coverage, onboarding friction	No tools — Perplexity has built-in web search; repo metadata injected into task
Enterprise Architect	Anthropic Claude Sonnet 4	Coupling, service boundaries, API surface, import depth	Uses FileReader, ImportGraph, APIScanner tools
Security & Resilience Analyst	Perplexity Sonar Pro	Secrets, vulnerable deps, auth, error handling	Tools pre-run in Python; results + live CVE knowledge via Perplexity
DA Chair	OpenAI GPT-4.1	Evidence synthesis, conflict resolution, final ruling	Weighted scoring across all specialist reports

Why different LLMs?

Deliberate diversity — each LLM has different strengths:

GPT-4.1: Strong instruction-following, reliable structured output
Perplexity Sonar Pro: Live web search for real-time CVE lookups and community health data
Claude Sonnet 4: Deep reasoning for architectural and integration analysis

LLM Tool Compatibility Note

Not all LLMs support tool calling in CrewAI's ReAct loop. Perplexity Sonar Pro rejects OpenAI-style function calling entirely. For agents using Perplexity, tools are pre-run in Python before the crew starts and results are injected directly into the task description — giving the agent full evidence without needing to call tools itself. This is intentional and documented in the agent source files.

Features

Multi-LLM Council: 3 different LLM providers for genuine perspective diversity
Real-time Streaming: Watch agents deliberate via Server-Sent Events
Parallel Evaluation: Specialist agents execute in parallel (sequential only for DA Chair synthesis)
Codebase Review: Clone any GitHub repo and run the full council against actual code
Secret Scanning: Pre-run secret scanner with file-level evidence injected into security analysis
Live CVE Lookup: Perplexity brings current vulnerability data to dependency assessments
Governance Config: Per-instance governance rules loaded at runtime
Export: Full markdown report export for every review
Ask Questions: Post-review Q&A against completed analysis
Docker Support: Full docker-compose setup for production deployment

Tech Stack

Backend

CrewAI — Multi-agent orchestration
FastAPI — REST API & SSE streaming
LiteLLM — Unified LLM provider interface
Python 3.11+ with uv

Frontend

Next.js 14 — React framework with App Router
Tailwind CSS — Dev/DevOps aesthetic
Framer Motion — Agent panel animations
TypeScript

Tools (Codebase Review)

FileReaderTool — reads source files from the cloned repo
SecretScannerTool — scans for hardcoded credentials and key files
ImportGraphTool — analyses Python/JS import graphs and coupling
APIEndpointScannerTool — catalogues API routes and surface
StructureAnalyserTool — directory structure and language breakdown
TestCoverageTool — test file ratio and framework detection
DependencyCheckTool — dependency health and vulnerability signals
ComplianceCheckTool — governance rule evaluation

Quick Start

Prerequisites

Python 3.11+
uv
Bun (or npm)
API keys for OpenAI, Anthropic, and Perplexity

Local Development

Clone the repository

git clone https://github.com/JustinNarracott/Architect-Council.git
cd Architect-Council

Set up environment variables

cp .env.example .env
# Fill in your API keys

Install backend dependencies
```
uv sync
```
Install frontend dependencies
```
cd frontend && bun install
```

Start backend (from project root)

uv run architecture-council
# API available at http://localhost:8000

Start frontend (separate terminal)

cd frontend && bun dev
# UI available at http://localhost:3000

Docker (Recommended for Production)

cd docker
docker compose up --build -d
# Backend: http://localhost:8011
# Frontend: http://localhost:3011

Configuration

Required Environment Variables

Variable	Description	Used By
`OPENAI_API_KEY`	OpenAI API key	Standards Analyst, DA Chair (GPT-4.1)
`ANTHROPIC_API_KEY`	Anthropic API key	Enterprise Architect (Claude Sonnet 4)
`PERPLEXITY_API_KEY`	Perplexity API key	DX Analyst, Security Analyst (Sonar Pro)

Optional

Variable	Default	Description
`HOST`	`0.0.0.0`	Backend host
`PORT`	`8000`	Backend port
`RELOAD`	`false`	Hot reload (dev only)

Note: Google/Gemini is no longer used. The Enterprise Architect was migrated to Claude Sonnet 4 for more reliable tool calling in CrewAI's ReAct loop.

API Reference

ADR Review

Method	Endpoint	Description
`GET`	`/health`	Health check
`GET`	`/api/panel`	List council members and their LLMs
`POST`	`/api/review`	Start ADR review
`GET`	`/api/stream/{id}`	SSE stream for review progress
`GET`	`/api/review/{id}`	Get completed review
`GET`	`/api/rulings`	List past rulings

Codebase Review

Method	Endpoint	Description
`GET`	`/api/codebase/panel`	List codebase council members
`POST`	`/api/codebase/analyse`	Start codebase review (GitHub URL or local path)
`GET`	`/api/codebase/stream/{id}`	SSE stream for codebase review
`GET`	`/api/codebase/review/{id}`	Get completed codebase review

Example: Start Codebase Review

curl -X POST http://localhost:8000/api/codebase/analyse \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/your-org/your-repo.git"
  }'

Example: Start ADR Review

curl -X POST http://localhost:8000/api/review \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add Redis caching layer to Customer API",
    "technology": "Redis 7.x (AWS ElastiCache)",
    "reason": "Reduce database load and improve p95 latency from 800ms to <200ms",
    "affected_services": ["customer-api", "order-service"],
    "data_classification": "OFFICIAL",
    "proposer": "Platform Team"
  }'

Project Structure

Architect-Council/
├── backend/
│   ├── agents/           # Agent definitions — one file per agent, one LLM per agent
│   │   ├── standards_analyst.py
│   │   ├── dx_analyst.py
│   │   ├── enterprise_architect.py
│   │   ├── security_analyst.py
│   │   └── da_chair.py
│   ├── crews/
│   │   ├── architecture_crew.py   # ADR review crew
│   │   └── codebase_crew.py       # Codebase review crew (with pre-run tool injection)
│   ├── tools/            # 8 evaluation tools for codebase review
│   ├── schemas/          # Pydantic models
│   ├── api/
│   │   ├── routes.py             # ADR review endpoints
│   │   ├── codebase_routes.py    # Codebase review endpoints
│   │   ├── governance_routes.py  # Governance config endpoints
│   │   └── query_routes.py       # Post-review Q&A endpoints
│   ├── indexer/          # Repo cloning and indexing pipeline
│   ├── governance/       # Governance rule loading and formatting
│   └── main.py
├── frontend/
│   ├── app/
│   │   ├── page.tsx              # ADR Review
│   │   ├── codebase/page.tsx     # Codebase Review
│   │   └── governance/page.tsx   # Governance Config
│   ├── components/
│   └── lib/
├── docker/
│   ├── docker-compose.yml
│   ├── Dockerfile.backend
│   └── Dockerfile.frontend
├── governance/
│   └── defaults/         # Default governance rules (YAML)
├── data/                 # Static config (tech radar, patterns, compliance rules)
├── .env.example
├── pyproject.toml
└── CLAUDE.md             # Scope control for AI-assisted development

How It Works

ADR Review Flow

User submits an ADR (title, technology, reason, affected services, data classification)
Four specialist agents evaluate in parallel (~30–60 seconds)
DA Chair synthesises all assessments into a weighted ruling
Result streamed live via SSE; full report available for export

Codebase Review Flow

User submits a GitHub URL (or local path)
Indexer clones the repo and builds metadata (file tree, language breakdown, dependencies, key files)
Security tools (SecretScannerTool, FileReaderTool) are pre-run in Python and results injected into the security task description — this is required because Perplexity doesn't support function calling
Four specialist agents evaluate in parallel against the indexed repo
DA Chair synthesises with weighted scoring and produces a prioritised improvement roadmap

Governance

The council respects a governance configuration that can be set per-instance via the Governance Config UI or API. Governance rules influence agent scoring thresholds, mandatory findings, and compliance checks. Default rules are in governance/defaults/.

CI / Quality Gates

Every push runs:

Ruff lint check (uv run ruff check backend/)
mypy type check (uv run mypy backend/)
pytest test suite
Across Python 3.11, 3.12, and 3.13

Frontend CI runs bun lint and bun build on every push.

Contributing

Contributions welcome. Please read CONTRIBUTING.md first.

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit with clear messages
Ensure CI passes before opening a PR
Open a Pull Request

License

MIT — see LICENSE.

Acknowledgements

CrewAI for multi-agent orchestration
OpenAI, Anthropic, Perplexity for LLM APIs
Inspired by real design authority boards and architecture review processes

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
data		data
docker		docker
frontend		frontend
governance/defaults		governance/defaults
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
clean-build.bat		clean-build.bat
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

The Architecture Council

Overview

Two Modes

ADR Review

Codebase Review

The Council Panel

Why different LLMs?

LLM Tool Compatibility Note

Features

Tech Stack

Backend

Frontend

Tools (Codebase Review)

Quick Start

Prerequisites

Local Development

Docker (Recommended for Production)

Configuration

Required Environment Variables

Optional

API Reference

ADR Review

Codebase Review

Example: Start Codebase Review

Example: Start ADR Review

Project Structure

How It Works

ADR Review Flow

Codebase Review Flow

Governance

CI / Quality Gates

Contributing

License

Acknowledgements

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages