# System Mapping

> Map systems with diagrams—components, data flows, feedback loops, and causal relationships. Use for architecture understanding or stakeholder communication.

- Skill: `charlieviettq/system-mapping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add charlieviettq/system-mapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charlieviettq/system-mapping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: charlieviettq (https://skillmd.com/u/charlieviettq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charlieviettq/system-mapping

---


# System Mapping

Lightweight system mapping before deep implementation or refactor. Produces diagrams and narrative that clarify boundaries and dependencies.

## When to use

- Onboarding to unfamiliar codebase or pipeline
- Planning integration between services
- Explaining credit/ML/data flows to stakeholders

## When not to use

- Formal ADR decision (use `architecture-decision-records`)
- Auto-generating code from diagram

## Workflow

1. **Scope** — system boundary; actors; in/out of scope
2. **Components** — services, stores, queues, humans, external APIs
3. **Flows** — primary happy path; note sync vs async
4. **Feedback** — loops, retries, batch vs realtime
5. **Risks** — single points of failure, PII paths, manual steps
6. **Diagram** — Mermaid or C4-style; keep readable in markdown

## Diagram tips

- Start context/container level; drill to component only where needed
- Label data classifications on flows with sensitive data
- Version diagram with date in doc title or footer

## Output template

```markdown
## System map: [name]
- **Purpose:**
- **Actors:**
- **Components:** (table: name, role, owner)
- **Primary flows:**
- **Diagram:** (mermaid block)
- **Open questions:**
```