serena-code-architecture

Architectural Analysis with Serena + Graphiti

This skill guides systematic architectural analysis using Serena's symbol-level understanding, with optional persistence to Graphiti knowledge graph.

When to Use This Skill

• Analyzing a new codebase before implementing changes
• Documenting existing architecture for a project
• Persisting architectural insights to memory
• Understanding dependencies and call hierarchies
• Building a knowledge graph from code structure

Analysis Workflow

Phase 1: Project Structure Discovery

Understand the high-level layout:

# Get directory structure
mcp__plugin_serena_serena__list_dir({
  "relative_path": ".",
  "recursive": false
})

# Identify key directories (src/, app/, lib/, etc.)
mcp__plugin_serena_serena__list_dir({
  "relative_path": "src",
  "recursive": true
})

Goal: Identify entry points, main modules, and organizational patterns.

Phase 2: Entry Point Analysis

Find the application entry points:

# Look for main/app files
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "if __name__.*==.*__main__|def main\\(|app\\s*=\\s*FastAPI|createApp",
  "restrict_search_to_code_files": true
})

# Get symbols from entry file
mcp__plugin_serena_serena__get_symbols_overview({
  "relative_path": "src/main.py",
  "depth": 1
})

Phase 3: Core Component Mapping

Identify and analyze major components:

# Find all service/controller/model classes
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "Service",
  "substring_matching": true,
  "include_kinds": [5],  # Class only
  "depth": 1
})

# For each major component, get full structure
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "AuthService",
  "include_body": false,
  "depth": 1  # Get methods
})

Phase 4: Dependency Tracing

Understand how components connect:

# Find who uses AuthService
mcp__plugin_serena_serena__find_referencing_symbols({
  "name_path": "AuthService",
  "relative_path": "src/services/auth.py"
})

# Find what AuthService depends on
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "AuthService/__init__",
  "include_body": true
})

Phase 5: Create Architectural Memories (Optional)

Store findings using Graphiti MCP:

# Load config (run once)
source "$HOME/.config/claude/graphiti-context-hub.conf" 2>/dev/null

GROUP_ID="${GRAPHITI_GROUP_ID:-main}"
REPO_NAME=$(git remote get-url origin 2>/dev/null | sed 's/.*\///' | sed 's/\.git$//' || basename "$PWD")

# Save architectural finding to Graphiti
# IMPORTANT: Prefix episode_body with "Repo: {REPO_NAME}\n\n"
result = mcp__graphiti__add_memory({
    "name": "AuthService: Core authentication component",
    "episode_body": f"""Repo: {REPO_NAME}

AuthService handles JWT validation, user sessions, and OAuth flows. Dependencies: UserRepository, TokenService, CacheService. Used by: all API endpoints via middleware.""",
    "group_id": GROUP_ID,
    "source": "serena-analysis",
    "source_description": "Code architecture analysis via Serena"
})

Note: Graphiti automatically extracts entities and relationships from the episode body.

Phase 6: Exploring the Knowledge Graph (Optional)

Explore relationships between components:

# Search for related entities
nodes_result = mcp__graphiti__search_nodes({
    "query": "AuthService",
    "group_ids": [GROUP_ID],
    "max_nodes": 10
})

# Get facts showing relationships
facts_result = mcp__graphiti__search_memory_facts({
    "query": "AuthService dependencies relationships",
    "group_ids": [GROUP_ID],
    "max_facts": 20
})

Note: Graphiti automatically creates entities and relationships from saved memories.

Architectural Patterns

When saving architectural insights, include:

• Component Purpose: What the component does
• Dependencies: What it requires/uses
• Dependents: What uses it
• Patterns: Design patterns employed
• External Connections: APIs, databases, services

Graphiti will automatically extract:

• Entities (components, services, classes)
• Relationships (depends_on, uses, extends, implements)
• Temporal relationships (created_before, modified_after)

Example: FastAPI Project Analysis

# 1. Find routers
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "APIRouter\\(\\)|router\\s*=",
  "restrict_search_to_code_files": true
})

# 2. Analyze router structure
mcp__plugin_serena_serena__get_symbols_overview({
  "relative_path": "src/routers/users.py",
  "depth": 1
})

# 3. Find dependency injection
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "Depends\\(",
  "restrict_search_to_code_files": true,
  "context_lines_before": 1,
  "context_lines_after": 1
})

# 4. Trace service dependencies
mcp__plugin_serena_serena__find_referencing_symbols({
  "name_path": "get_current_user",
  "relative_path": "src/dependencies/auth.py"
})

# 5. Create architecture memory
result = mcp__graphiti__add_memory({
    "name": "FastAPI app structure: Routers + Dependencies",
    "episode_body": f"""Repo: {REPO_NAME}

App uses router-based organization with dependency injection. Routers: /users, /auth, /products. Dependencies: get_current_user, get_db. All routes require auth except /auth/login.""",
    "group_id": GROUP_ID,
    "source": "serena-analysis",
    "source_description": "FastAPI architecture analysis"
})

Analysis Checklist

• Directory structure mapped
• Entry points identified
• Major components catalogued
• Dependencies traced
• External connections documented
• Key patterns identified
• Architectural insights saved to memory
• Knowledge graph explored (if needed)

Tips

1. Work incrementally - Don't try to analyze everything at once
2. Focus on interfaces - Public methods/APIs matter more than internals
3. Document decisions - Create memories for WHY, not just WHAT
4. Include context - Dependencies, dependents, patterns
5. Rich episode content - Include detailed descriptions for better entity extraction by Graphiti