Architecture Explainer — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Architecture Explainer (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
This skill directs the agent to explore a codebase or system description and produce a clear, structured architecture overview. It maps out layers, major components, data flows, and external dependencies, then renders ASCII diagrams showing how the pieces connect. The result is a document a new engineer could read in 10 minutes and understand how the system works.
Use this when onboarding new team members, preparing for an architecture review, creating documentation for a system you inherited, or clarifying your own mental model before a large refactor.
Copy this file to .agents/skills/architecture-explainer/SKILL.md in your project root.
Then ask:
Add the instructions below to your .cursorrules or paste them into the Cursor AI pane before asking for the architecture overview.
Provide a directory listing or paste key files and ask Codex to follow the instructions below to produce the architecture document.
When asked to explain or document an architecture, follow these steps:
Start by reading:
package.json, pyproject.toml, go.mod, or the equivalent dependency manifestmain.ts, index.ts, app.py, cmd/main.go)index or README files if presentDo not read every file. Use the directory structure and entry points to infer the layering.
Extract:
For the most important 2–3 user-facing operations, trace:
Format the output as follows:
# Architecture Overview — [Project Name]
## System Summary
[2–3 sentences. What does this system do? What are the key technical choices (language, framework, DB)?]
## Layer Diagram
[ASCII diagram showing the main layers top-to-bottom, e.g.:]
┌─────────────────────────────────┐
│ Client / Browser │
└────────────────┬────────────────┘
│ HTTP / REST
┌────────────────▼────────────────┐
│ Express API Server │
│ routes/ → controllers/ → ... │
└──────┬─────────────┬────────────┘
│ │
┌──────▼──────┐ ┌────▼────────────┐
│ PostgreSQL │ │ Redis Cache │
└─────────────┘ └─────────────────┘
## Component Breakdown
### [Component Name]
- **Location**: `src/payments/`
- **Responsibility**: [1–2 sentences]
- **Depends on**: [List of other components or external services]
- **Depended on by**: [Who calls this]
[Repeat for each major component]
## Key Data Flows
### [Flow name, e.g., "User places an order"]
1. Request arrives at `POST /api/orders`
2. `OrderController` validates the request body
3. `OrderService` runs business logic and calls `PaymentService`
4. `PaymentService` calls Stripe API
5. On success, `OrderRepository` writes to `orders` table
6. Response returned to client
[Repeat for 2–3 key flows]
## External Dependencies
| Dependency | Purpose | Where integrated |
|------------|---------|-----------------|
| PostgreSQL | Primary data store | `server/db/` |
| Redis | Session cache | `server/cache/` |
| Stripe | Payment processing | `server/services/payment.ts` |
## What is NOT covered here
[Note any parts of the system this document doesn't address, e.g., "Worker queue jobs not documented"]After writing the document, re-read the entry point files and check that every major path through the system is accounted for. If something doesn't fit your model, revise the model — don't ignore the discrepancy.
Input to Agent:
"Use the Architecture Explainer skill on this repo. Here's the directory tree: `` src/ api/routes/ api/controllers/ services/ db/repositories/ workers/ client/ pages/ components/ ``"Output from Agent:
# Architecture Overview — MyApp
>
## System Summary MyApp is a full-stack web application built with Node.js/Express on the backend and React on the frontend. It uses PostgreSQL for persistence and background workers for async processing.
>
## Layer Diagram
>
`` ┌──────────────────────────┐ │ React Client (client/) │ └────────────┬─────────────┘ │ HTTP/JSON ┌────────────▼─────────────┐ │ Express API (src/api/) │ │ routes/ → controllers/ │ └──────┬───────────────────┘ │ ┌──────▼───────────────────┐ │ Services (src/services/) │ └──────┬───────────────────┘ │ ┌──────▼───────────────────┐ ┌──────────────────┐ │ Repositories (src/db/) │ │ Workers │ └──────┬───────────────────┘ │ (src/workers/) │ │ └──────────────────┘ ┌──────▼───────────────────┐ │ PostgreSQL │ └──────────────────────────┘ ``>
## Component Breakdown
>
### API Routes - Location: src/api/routes/ - Responsibility: Maps HTTP methods and paths to controller functions - Depends on: Controllers>
### Services - Location: src/services/ - Responsibility: Contains all business logic; orchestrates calls between repositories and external APIs - Depends on: Repositories, external APIs - Depended on by: Controllers, Workers~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.