Architect Ai

ArchitectAI — Free Study Tool for the Claude Certified Architect Exam

The codebase IS the curriculum — every file demonstrates an exam concept in production code.

[](https://github.com/aviraldua93/architect-ai/stargazers) [](LICENSE) [](https://github.com/aviraldua93/architect-ai/actions/workflows/ci.yml) [](tsconfig.json)

---

What Is This?

ArchitectAI is an open-source study tool for the Claude Certified Architect (Foundations) exam — but with a twist: the codebase itself teaches you the exam concepts. Every architectural decision, every file, every pattern maps directly to one of the 30 exam task statements across 5 domains.

You don't just read about agentic loops — you see a production implementation in src/agents/loop.ts. You don't just memorise hook patterns — you see PostToolUse normalisation running live in src/agents/hooks.ts.

> 🆓 No API key required for Tier 1. 162 practice questions, CLI quiz, timed exam simulation, spaced repetition — completely free and offline.

Feature Status

| Feature | Status | Notes | |---------|--------|-------| | CLI Quiz (quiz) | ✅ Shipped | 132 questions across all 5 domains | | Timed Exam Simulation (exam) | ✅ Shipped | 60-question mock exam, 120-min timer, domain-weighted, 720/1000 pass threshold | | Adaptive Study (study) | ✅ Shipped | SM-2 spaced repetition, domain filtering, source code references | | Exam Readiness (assess) | ✅ Shipped | Per-domain scoring, weak area identification, study recommendations | | Progress Dashboard (dashboard) | ✅ Shipped | Terminal dashboard with domain bars, streak tracking, SRS due count | | Web UI | ✅ Shipped | Next.js app at localhost:3939 — quiz with filters, dashboard, dark mode, mobile-responsive | | MCP Server | ✅ Shipped | Full JSON-RPC 2.0 server with resources, tools, and prompts | | Exam Scenarios | ✅ Shipped | 6 production scenarios with 30 linked questions matching official CCA-F format | | Concept Deep-Dives | 🚧 Planned | In-depth explanations for all 30 task statements |

Quick Start

git clone https://github.com/aviraldua93/architect-ai.git && cd architect-ai
npm install
npx architect-ai quiz

Or install globally:

npm install -g architect-ai
architect-ai quiz

> 💡 That's it. No API key, no account, no cost. Just quiz and start practicing.

More Commands

architect-ai exam                  # Timed 60-question mock exam
architect-ai study --domain 1      # Adaptive study with spaced repetition
architect-ai assess                # Exam readiness prediction
architect-ai dashboard             # Progress tracking dashboard

Web UI

cd web && npm install && npm run dev   # Opens at http://localhost:3939

Three Ways to Learn

🖥️ Tier 1 — Static CLI

No API Key Required

105 scenario-based questions across all 5 exam domains. Timed exam simulation. Spaced repetition. Progress tracking.

Works offline. Works on a plane.

ZERO COST.

🔌 Tier 2 — MCP Server

No API Key Required

Plugs into your existing Claude Desktop, GitHub Copilot, or any MCP client.

Our server provides content + tools. Your AI provides intelligence.

ZERO COST.

🤖 Tier 3 — Live Agents

Bring Your Own Key

Full multi-agent orchestration with adaptive study sessions, Socratic dialogue, and weakness detection.

You provide your own Claude API key.

~$0.02–0.05 per session. FULL POWER.

Exam Coverage

Every file maps to a specific exam domain and task statement:

| Domain | Weight | Source Directory | Key Concepts | |--------|--------|-----------------|--------------| | 1. Agentic Architecture | 27% | src/agents/ | Agentic loops, multi-agent orchestration, subagent context passing, workflow enforcement, SDK hooks, task decomposition, session state | | 2. Tool Design & MCP | 18% | src/tools/, src/mcp/ | Tool descriptions, error schemas, tool_choice modes, MCP resources/tools/prompts, built-in tools | | 3. Claude Code Config | 20% | src/cli/, .claude/ | CLAUDE.md hierarchy, slash commands, path rules, plan mode, iterative refinement, CI/CD | | 4. Prompt Engineering | 20% | src/prompts/ | Explicit criteria, few-shot examples, structured output, validation-retry, batch API, multi-instance review | | 5. Context & Reliability | 15% | src/context/ | Context preservation, escalation patterns, error propagation, codebase exploration, human review, provenance |

Usage

# Tier 1: Offline study (no API key needed)
npx architect-ai quiz              # Quick practice questions
npx architect-ai quiz -d 1         # Filter by domain (1-5)
npx architect-ai quiz -t 1.2       # Filter by task statement

# Tier 2: MCP server (plug into Claude Desktop / Copilot)
npm run mcp                        # Start MCP server

# Tier 3: Live agents (requires ANTHROPIC_API_KEY — coming soon)
export ANTHROPIC_API_KEY=your-key   # macOS/Linux
# $env:ANTHROPIC_API_KEY="your-key" # Windows PowerShell
npm run agent                       # Adaptive study session

Project Structure

architect-ai/
├── CLAUDE.md                    ← Domain 3: Claude Code configuration
├── .claude/commands/            ← Domain 3: Slash commands (/study, /quiz, /explain, /assess)
├── .claude/rules/               ← Domain 3: Path-specific rules
├── src/
│   ├── agents/                  ← Domain 1: Agentic Architecture (27%)
│   │   ├── coordinator.ts          Hub-and-spoke orchestration (1.2)
│   │   ├── loop.ts                 Agentic loop lifecycle (1.1)
│   │   ├── spawner.ts              Subagent invocation (1.3)
│   │   ├── workflow-enforcer.ts    Programmatic enforcement (1.4)
│   │   ├── hooks.ts                PostToolUse & interception hooks (1.5)
│   │   ├── decomposer.ts           Task decomposition strategies (1.6)
│   │   └── session-state.ts        Session management & resumption (1.7)
│   ├── tools/                   ← Domain 2: Tool Design (18%)
│   │   ├── definitions.ts           Tool schemas & descriptions (2.1)
│   │   └── error-handling.ts        Structured error responses (2.2)
│   ├── mcp/                     ← Domain 2: MCP Integration
│   │   └── server.ts                MCP server: resources, tools, prompts (2.4)
│   ├── prompts/                 ← Domain 4: Prompt Engineering (20%)
│   │   ├── system-prompts.ts        Agent persona & constraints (4.1)
│   │   ├── few-shot.ts              Example banks & dynamic selection (4.2)
│   │   └── output-schemas.ts        Zod validation & retry loops (4.3)
│   ├── context/                 ← Domain 5: Context Management (15%)
│   │   ├── session-manager.ts       Session save/load/resume/fork (1.7, 5.1)
│   │   ├── progress-tracker.ts      Weighted scoring & spaced repetition (5.1)
│   │   └── escalation.ts            Tier 1→2→3 escalation patterns (5.2)
│   ├── cli/                     ← Domain 3: CLI & Commands (20%)
│   └── content/                 ← Pre-generated study material
│       └── questions/              105 scenario-based questions
├── web/                         ← Next.js web UI (in progress)
├── test/
│   ├── tier1/                   ← Free static validation (<5s)
│   ├── tier2/                   ← E2E with real Claude (~$3-4/run)
│   └── tier3/                   ← LLM-as-judge quality checks (~$0.15/run)
└── docs/                        ← Architecture & contributor guides

Question Banks

| Domain | Questions | Status | |--------|-----------|--------| | 1 — Agentic Architecture | 30 | ✅ Complete | | 2 — Tool Design & MCP | 20 | ✅ Complete | | 3 — Claude Code Config | 20 | ✅ Complete | | 4 — Prompt Engineering | 20 | ✅ Complete | | 5 — Context & Reliability | 15 | ✅ Complete | | Total | 105 | |

The Meta-Pattern

This project practices what it preaches. The way it's built IS a demonstration of exam concepts:

• This README → You're reading structured context passing (Domain 5)
• The org that built this → Hub-and-spoke multi-agent orchestration (Domain 1.2)
• Branch protection + CI → Programmatic enforcement over prompt-based guidance (Domain 1.4)
• 3-tier testing → Task decomposition: per-file analysis + cross-file integration (Domain 1.6)
• MCP server architecture → Tool design with proper descriptions and error schemas (Domain 2.1, 2.2)

Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide — branch naming, PR process, testing, code style, and how to add questions.

About

ArchitectAI is an aviraldua93 project — built by Aviral Dua using the very agentic patterns it teaches.

---

Preparing for the Claude Certified Architect exam? Star this repo and start with Tier 1. No API key. No cost. Just learning.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aviraldua93
• Source: aviraldua93/architect-ai
• License: MIT
• Homepage: https://github.com/aviraldua93/architect-ai#readme

Install and usage instructions live in the source repository linked above.