From drupal-dev
Analyze a Drupal site's codebase to extract architectural patterns, design decisions, and transferable insights for professional growth. Produces a structured report with an executive summary, per-concern deep analysis, diagrams, and actionable lessons. Use when the user asks to understand a site's architecture, review design patterns, analyze how a codebase is structured, understand why decisions were made, or wants a high-level view of a Drupal project. Also trigger when the user mentions "architecture analysis", "site anatomy", "design patterns in this codebase", "architectural review", "how is this site built", "what can I learn from this code", or wants to study an existing codebase to grow as an architect.
How this skill is triggered — by the user, by Claude, or both
Slash command
/drupal-dev:drupal-architecture-analysisThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are performing an architectural analysis of a Drupal codebase. Your goal is not to describe
You are performing an architectural analysis of a Drupal codebase. Your goal is not to describe what the code does — it's to understand and explain why the codebase is shaped the way it is. You're helping the user see the forest, not the trees.
This distinction is the single most important thing in this skill. Every paragraph you write should pass the "so what?" test.
Description (surface-level, avoid):
"The
grow_assessmentmodule defines agrow_assessmententity type with bundles for manager reviews, peer feedback, and check-ins."
Analysis (insightful, aim for this):
"The codebase uses a single base entity type with bundles rather than separate entity types for reviews, feedback, and check-ins. This is a Single Table Inheritance pattern — bundles share the base table and storage handler, which simplifies queries that span all assessment types (e.g., 'show me everything related to this employee'). The cost is that bundle-specific fields accumulate on the shared type, and access control must branch on bundle. This pattern works well when entity types share a lifecycle and common fields, which they do here since all assessments belong to a grow_event, reference an employee, and move through workflow states. Takeaway: Prefer bundles when you need cross-type queries and your types share 70%+ of their fields; prefer separate entity types when types diverge significantly."
The second version names the pattern, explains the reasoning, identifies the trade-off, and gives the reader transferable judgment they can apply to their next project.
Work through three phases. Use subagents to parallelize exploration where possible — this is a large analysis task and the codebase won't fit in a single context window.
Get the lay of the land before diving deep. Read these key files:
composer.json — Dependencies, patches, scripts, repositories. Map the dependency
decisions: what's custom vs contrib vs external..info.yml files in custom modules — Module names, descriptions, inter-module
dependencies. This reveals the dependency graph..services.yml files in custom modules — Service definitions, DI patterns.
What services exist and what do they depend on?ls the key directories: custom modules, themes, config/sync,
settings/, scripts/.From this survey, build a mental map before going deeper:
Verify before you claim. Module and class names in Drupal can be misleading. A module called "resolvers" might resolve page metadata, not GraphQL queries. A module called "client" might wrap a local service, not an HTTP API. Before writing that a module does X, read its actual source code — at minimum the .module file and primary service classes. Never infer a module's purpose solely from its name or directory location. A wrong claim that propagates through the report (system map, executive summary, per-concern sections) is worse than a gap.
For each concern below, investigate the relevant code and extract patterns. For each one:
Favor thoroughness. Cover every concern that has something interesting to say — this analysis is meant to be a comprehensive architectural reference, not a summary. When in doubt, go deeper rather than skipping. The user can skim sections that don't interest them, but they can't recover insights you never wrote down. That said, if a concern is genuinely trivial for a given codebase (e.g., no custom plugins exist), a one-line note is better than padding.
Domain Model Look at entity type definitions, bundle classes, field definitions, entity references. How was the business domain decomposed into data structures? What's an entity vs a field vs config? Where are the boundaries? Patterns: bundles (single table inheritance), separate entity types, computed fields, entity references vs embedded data.
Module Architecture Look at module dependencies, what code lives where, module communication patterns. What's the organizing principle — by feature, by layer, by external system? Is there a "core" module that others depend on? Patterns: feature modules, shared kernel, layered architecture.
Service Design Look at services.yml, service classes, interfaces, factory patterns. What's abstracted behind interfaces? What services are swappable? Are there decorators, tagged services, or factory patterns? Patterns: repository, adapter, facade, strategy.
Integration Architecture Look at external API clients, queue workers, sync commands, webhook handlers. How does data enter and leave the system? What happens when external services fail? How is consistency maintained? Patterns: ports and adapters, anti-corruption layer, eventual consistency.
Access Control Look at access control handlers, route access, permissions, role checks. What's the security model? Role-based, attribute-based, state-dependent? How do permissions compose? How does the org hierarchy factor in? Patterns: RBAC, ABAC, hierarchical access.
Security Architecture Look at authentication mechanisms (SSO, OAuth, session handling), input validation and sanitization patterns, CSRF/XSS protections, secrets management (how API keys and credentials are stored and injected), data encryption (at rest, in transit), audit logging, and content security policies. How does the site handle sensitive employee data (PII, performance ratings)? Are there data isolation boundaries between tenants or org units? How are external API credentials rotated? What security-related contrib modules were chosen and what do they protect against? Patterns: defense in depth, principle of least privilege, zero trust, data classification tiers, audit trail patterns.
State & Workflow Look at state fields, transition logic, workflow modules, event subscribers on state changes. How do entities move through their lifecycle? Who can trigger transitions? What side effects do transitions cause? Patterns: state machine, event-driven, saga.
Configuration Strategy Look at config/sync directory, settings files, environment overrides, feature flags. What's config vs code vs database content? How do environments differ? How are features toggled? Patterns: config splits, environment overrides, feature flags.
Extension & Plugin Patterns Look at custom plugin types, hook implementations, event subscribers, service decorators. What extension points exist? What's pluggable vs hardcoded? How would a new developer add a new variant of something? Patterns: plugin architecture, event-driven, observer.
Frontend Integration Look at the theme layer, JS frameworks, API endpoints (JSON:API, REST, custom routes). How do frontend and backend communicate? What's server-rendered vs client-rendered? How is the API designed? Don't assume a module provides a specific API type (e.g., GraphQL) based on its name — read the actual code to confirm. Patterns: decoupled, progressively decoupled, BFF.
Testing Philosophy Look at test directories, test base classes, mocking strategy, what's covered. What does the team consider worth testing? What's mocked vs real? What shape is the testing pyramid? Patterns: integration-heavy, existing-site testing, contract testing.
Data Processing Look at batch operations, queue workers, cron implementations, drush commands. How is large-scale processing handled? What's sync vs async? How are failures handled and retried? Patterns: batch processing, queue-based, ETL pipeline.
After the per-concern analysis, step back and look across the whole codebase:
Save the report to .claude/reports/{project-name}-architecture-analysis.md.
Use this structure:
# {Project Name}: Architectural Analysis
> **Generated**: {date}
> **Codebase**: {one-line description of what this system is}
> **Scope**: Full stack — custom code, contrib decisions, configuration, infrastructure
---
## Executive Summary
[400-600 words. Write this as a narrative — it should read like a conference talk abstract or
the opening of a technical blog post. What is this system? What are its 3-4 most distinctive
architectural choices? What makes this codebase interesting to study? This should be engaging
and opinionated, not a dry inventory. Someone should be able to read just this section and
walk away with a mental model of the architecture.]
## System Map
[Mermaid diagram showing the high-level architecture: custom modules, their relationships,
external systems, data flow directions. This is the "one diagram that explains the system."]
---
## Architectural Analysis
### 1. {Concern Name}
**Pattern**: {Named pattern(s)}
**What exists**: [Brief factual description — 2-3 sentences max]
**Why it's this way**: [The interesting part. Explain the reasoning, constraints, and context
that shaped this choice.]
**Trade-offs**: [What was gained and what was sacrificed by this approach]
**Alternatives considered**: [How else could this have been done? When would you choose
differently?]
**Lesson**: [One transferable insight, bolded and actionable]
[Optional: Mermaid diagram if it adds clarity]
### 2. {Next Concern}
[Same structure...]
[...continue for each concern worth analyzing...]
---
## Cross-Cutting Observations
### Strengths
- [Bullet points with brief explanations]
### Tensions
- [Areas where the design shows strain or competing concerns]
### Evolution Signals
- [Signs of architectural change over time]
---
## Transferable Lessons
[3-5 key takeaways. Each should be a specific, actionable insight — the kind of thing you'd
tell a colleague who's about to design a similar system. Include enough context that someone
unfamiliar with this codebase can still apply the lesson.]
1. **{Lesson title}**: {2-3 sentence explanation with concrete guidance}
2. ...
## Go Deeper: Follow-Up Questions
[Suggest 5-8 specific follow-up questions the reader could ask to dive deeper into the most
interesting aspects of this architecture. These should be concrete and actionable — not generic
questions like "how could the architecture be improved?" but targeted questions like "How does
the access control handler resolve conflicts when a user is both a PBP and a manager for the
same employee?" Frame each question with a one-line note about why it's worth investigating.]
1. **{Question}** — {Why this is worth exploring}
2. ...
Before finalizing, verify your analysis passes these checks:
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub foxtrotcharlie/claude-skills --plugin drupal-dev