# Trace Backend Flow

> Use when analyzing backend services, APIs, RPC handlers, message consumers, schedulers, jobs, domain/application services, repositories, transactions, persistence, events, external dependencies, or cross-service business flows.

- Skill: `xylvvv/trace-backend-flow` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add xylvvv/trace-backend-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xylvvv/trace-backend-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xylvvv (https://skillmd.com/u/xylvvv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xylvvv/trace-backend-flow

---


# Trace Backend Flow

## Purpose

Use this skill to reconstruct backend business flows from code with an evidence trail. The goal is not to guess the architecture; it is to enumerate discovered entry points, trace representative and critical flows, and disclose uncertainty.

## Core Rules

- Prefer code evidence over inference. Mark anything without direct evidence as `inferred` or `unconfirmed`.
- Build an entry coverage matrix before writing the narrative flow.
- For every core step, record file path plus function, method, class, or configuration key.
- Do not claim invisible services, generated code, runtime registration, or unavailable repositories were fully analyzed.
- Keep independent business flows and backend projects in separate output directories.

## Output Layout

- Default each backend analysis leaf to `docs/trace-code-flow/<flow-slug>/backend/<project-slug>/`.
- Derive `<flow-slug>` from the business goal in lowercase hyphen-case, such as `create-order` or `user-login`.
- Derive `<project-slug>` from the service/application manifest or configuration name; fall back to the normalized project directory name.
- If one request covers multiple independent flows, create one `<flow-slug>` directory per flow.
- If one flow crosses multiple backend projects or services, create one `<project-slug>` directory per project.
- Treat a user-provided output path as the root for this layout unless the user explicitly identifies it as the final leaf directory.

## Workflow

1. Determine scope and assumptions.
   - Use the user-provided path first.
   - If the path is missing, infer likely backend roots from repository structure and document the assumption.
   - Record exclusions such as tests, generated files, vendor code, or unavailable sibling repositories.

2. Discover backend entry points.
   - Look for HTTP/API controllers, RPC handlers, CLI commands, scheduled jobs, MQ consumers, event listeners, webhooks, and framework route configuration.
   - Use `references/backend-search-patterns.md` when choosing search terms.
   - Produce an entry coverage matrix with status: `expanded`, `partially expanded`, or `not expanded`.

3. Trace each selected core flow.
   - Start at user/system trigger.
   - Continue through validation, authorization, orchestration, domain decisions, transaction boundaries, persistence, event publication, external calls, and response/acknowledgement.
   - Include critical failure paths: validation failure, idempotency hit, downstream timeout, retry exhausted, transaction rollback, compensation, dead-letter, or degraded response.

4. Reconstruct system interactions.
   - Separate internal calls from external dependencies.
   - Identify DB, cache, MQ, object storage, third-party APIs, SDKs, RPC/HTTP clients, and shared libraries.
   - For cross-service calls, record service/repository boundary, protocol, endpoint/topic, contract source, timeout, retry, circuit breaker/degradation, and idempotency key when visible.

5. Generate artifacts.
   - Use `references/backend-report-template.md` for the report structure.
   - In each selected backend leaf directory, generate:
     - `coverage-matrix.md`
     - `analysis-report.md`
     - `flow-core.puml`
     - `system-interaction.puml`
   - PlantUML is preferred for backend activity and sequence diagrams.

6. Validate diagrams with graceful fallback.
   - Use `$plantuml-check` when it is installed and available.
   - If it is unavailable, perform a minimal static check and state that render-level validation was not completed.
   - Do not send diagrams to remote PlantUML or Kroki services unless the user explicitly permits it.
   - PlantUML-compatible PNG/SVG rendering is valid evidence; generative or manually produced images are not.

## Evidence Format

Use this table shape for important steps:

| Step | Behavior | Evidence | Evidence Type | Confidence |
| --- | --- | --- | --- | --- |
| S1 | Receive create-order request | `src/order/OrderController.java#create` | direct | high |

Evidence types: `direct`, `configuration`, `test`, `generated`, `inferred`, `unconfirmed`.

## Completion Checklist

- Entry coverage matrix lists all discovered backend entries in scope.
- Report explains scope, assumptions, main flow, failure paths, data/state changes, external interactions, and risks.
- Each core step has code evidence.
- Cross-service or cross-repository jumps are explicit; unavailable downstream code is listed as not expanded.
- Diagram files and report describe the same flow and do not contradict each other.
- Diagram validation result or fallback reason is recorded.