explain_architecture
Traces real request, auth, billing, and data flows through the system and points you to the code that implements them.
DESCRIPTION
This tool is for end-to-end flow understanding, not raw file trees. Use it when the risk is in how components connect rather than in a single symbol implementation.
WHEN TO USE
GOOD FIT
- Before changing auth, billing, or request middleware.
- When debugging a request lifecycle issue.
- When onboarding to a service with multiple integrations.
- When you need the code path from request entry to persistence or third-party side effects.
AVOID IT WHEN
- You just need repo orientation; use get_project_context.
- You need exact code for a function; use read_code.
- You only need pattern search; use find_code.
PARAMETERS
| Name | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Repo root to analyze. |
| focus | string | No | Optional focus area such as "auth", "database", "billing", "api", or "queue". |
EXAMPLE
tools-call.json
{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "explain_architecture", "arguments": { "path": "/workspace/repo", "focus": "auth" } }}OUTPUT
response.json
{ "jsonrpc": "2.0", "id": 4, "result": { "content": [ { "type": "text", "text": "Entry: middleware.ts -> /api/mcp route\nAuth: Bearer key validated in src/lib/auth.ts\nRate limits: checked before tool dispatch\nPersistence: usage written to Supabase and Redis meter paths\nRisk points: auth bypasses, key rotation, 429 handling" } ] }}TOKEN EFFICIENCY
Architecture explanations compress multi-file flow reading into one summary, which saves tokens when the question is about connections and lifecycle rather than syntax.