Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The claude-code-showcase project demonstrates a comprehensive architecture for integrating the Claude LLM into a software development lifecycle. The system is designed to function as an automated, context-aware "super-powered teammate" by leveraging a structured configuration of project memory, domain-specific knowledge (Skills), specialized assistants (Agents), and event-driven automation (Hooks). This architecture aims to automate code generation, quality assurance, code reviews, and project maintenance tasks.
The core of the architecture is a set of configuration files within the .claude directory, which governs Claude's behavior, permissions, and integrations. External systems like JIRA and GitHub are integrated via MCP servers, while real-time code intelligence is provided by LSP servers. Automation is achieved through both local hooks that trigger on specific actions and CI/CD pipelines using GitHub Actions for tasks like PR reviews and scheduled maintenance.
Sources: README.md:3-8, README.md:73-88
Core Components
The architecture is composed of several key components that work in concert to provide a seamless developer experience. These include configuration files, knowledge documents, automation scripts, and integration definitions.
Sources: README.md:73-107
This diagram shows the high-level interaction between the developer, Claude Code, and the various architectural components within the project.
Sources: README.md:73-107
Configuration Layer
The foundation of the architecture is a set of configuration files that define the project's context, rules, and automation triggers.
Sources: README.md:128-129
CLAUDE.md - Project Memory
CLAUDE.md serves as Claude's persistent memory, loaded at the start of each session. It contains high-level information about the project, ensuring Claude has immediate context.
Sources: README.md:128-130, CLAUDE.md:1-4
Key information stored in CLAUDE.md includes:
- Project Stack: e.g., React, TypeScript, Node.js
- Key Commands:
npm test,npm run lint - Directory Structure:
src/components,src/api - Code Style: TypeScript strict mode, no
any - Critical Rules: Error handling, UI states, mutation patterns
Sources: CLAUDE.md:6-40
Claude searches for this file in a specific order of precedence:
.claude/CLAUDE.md./CLAUDE.md(project root)~/.claude/CLAUDE.md(user-level)
Sources: README.md:131-135
settings.json - Hooks & Environment
This file is the main configuration hub for defining hooks, environment variables, and permissions. It is located at .claude/settings.json.
Sources: README.md:143-146
It defines event-driven hooks that trigger custom commands or actions at different points in the workflow.
| Event | When It Fires | Use Case |
|---|---|---|
PreToolUse | Before tool execution | Block edits on main, validate commands |
PostToolUse | After tool completes | Auto-format, run tests, lint |
UserPromptSubmit | User submits a prompt | Add context, suggest skills |
Stop | Agent finishes execution | Decide if Claude should continue |
Sources: README.md:148-156
An example hook in settings.json prevents edits on the main branch:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
"timeout": 5
}
]
}
]
}
}
Sources: .claude/settings.json:3-16, README.md:114-126
Extensibility Layer
The system is made extensible through Skills, Agents, and Commands, which allow developers to teach Claude project-specific patterns and create reusable workflows.
Sources: README.md:8-10, README.md:315-318
Skills - Domain Knowledge
Skills are Markdown documents (SKILL.md) that teach Claude project-specific conventions, patterns, and best practices. They are stored in .claude/skills/{skill-name}/. Claude uses the description in the frontmatter to determine when to apply a skill.
Sources: README.md:315-318, .claude/skills/testing-patterns/SKILL.md:2-3
| Field | Required | Description |
|---|---|---|
name | Yes | Lowercase identifier, must match the directory name. |
description | Yes | Explanation of what the skill does and when to use it. Critical for activation. |
allowed-tools | No | Comma-separated list of tools Claude can use with this skill. |
model | No | Specific model to use for this skill (e.g., claude-sonnet-4-20250514). |
Sources: README.md:329-335
Agents - Specialized Assistants
Agents are specialized AI assistants defined in Markdown files (.claude/agents/{agent-name}.md). They have a focused purpose, a specific system prompt, and a defined set of tools. An example is the code-reviewer.md agent, which follows a detailed checklist to review code changes.
Sources: README.md:17-19, README.md:349-353, .claude/agents/code-reviewer.md:2-5
Automation Engine
Automation is a key aspect of the architecture, implemented through local hooks and CI/CD workflows.
Sources: README.md:11-13, README.md:20-25
Skill Evaluation Hooks
A powerful automation is the skill evaluation system, which runs on the UserPromptSubmit hook. It analyzes the user's prompt, file paths, and intent to automatically suggest relevant skills. This is configured in .claude/settings.json to trigger a script like .claude/hooks/skill-eval.sh.
Sources: README.md:27-29, README.md:255-259, README.md:297-308
The following diagram illustrates the skill evaluation flow.
Sources: README.md:261-277
GitHub Actions Workflows
The project uses GitHub Actions for automated, scheduled maintenance and quality control. These workflows invoke Claude to perform tasks directly on the repository.
Sources: README.md:20-25, README.md:386-392
Key workflows include:
- PR Code Review: Automatically reviews pull requests.
- Scheduled Docs Sync: Monthly check to ensure documentation is aligned with code.
- Scheduled Code Quality: Weekly review of random directories to find and fix issues.
- Scheduled Dependency Audit: Biweekly check for safe dependency updates.
Sources: README.md:394-397
The PR review workflow is triggered on pull request events or when @claude is mentioned in a PR comment. It uses the claude-code-action to execute the review based on the .claude/agents/code-reviewer.md agent.
This sequence diagram shows the PR review process.
External Integrations
The architecture supports integration with external tools and services through MCP and LSP servers.
Sources: README.md:167-170, README.md:220-223
MCP (Model Context Protocol) Servers
MCP servers act as a bridge between Claude Code and external APIs like JIRA, GitHub, and Slack. This enables complex workflows, such as reading a JIRA ticket, implementing the feature, and updating the ticket status automatically. Configuration is managed in the .mcp.json file at the project root.
Sources: README.md:30-34, README.md:167-173
This diagram shows how MCP servers connect Claude to external services.
Sources: README.md:175-179
An example .mcp.json configuration for JIRA integration:
{
"mcpServers": {
"jira": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic/mcp-jira"],
"env": {
"JIRA_HOST": "${JIRA_HOST}",
"JIRA_EMAIL": "${JIRA_EMAIL}",
"JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
}
}
}
}
Sources: .mcp.json:2-14, README.md:188-200
LSP (Language Server Protocol) Servers
LSP integration provides Claude with real-time code intelligence, similar to an IDE. This includes diagnostics (errors/warnings), type information, and code navigation. This dramatically improves the quality and accuracy of code generation. LSP support is enabled via plugins in .claude/settings.json.
Sources: README.md:220-226, .claude/settings.json:52-55
Summary
The claude-code-showcase architecture provides a powerful and flexible framework for integrating an LLM deeply into the development process. By combining persistent memory (CLAUDE.md), modular knowledge (Skills), task-specific Agents, and robust automation (Hooks, GitHub Actions), the system transforms Claude from a simple code generator into an active, context-aware development partner. The integration layers for external services (MCP) and code intelligence (LSP) further enhance its capabilities, enabling end-to-end workflow automation and higher-quality code output.
Sources: README.md:3-8, README.md:430-448