architecture-explainer

Category: Tools & Productivity | Uploader: gvkhosla | Downloads: 0 | Version: v1.0（Latest）

Explains your product's technical architecture in plain English — so you understand what's being built, can make informed decisions, and can describe it to others. Use when an agent has set up your tech stack and you're not sure how the pieces connect, or when you need to explain your system to a potential co-founder, investor, or hire. Produces an architecture-overview.md in plain language with a simple diagram.

Changelog: Source: GitHub https://github.com/gvkhosla/founder-skills

Directory Structure

Current level: skills/build/architecture-explainer/

📄 SKILL.md 6.7 KB

SKILL.md

---
name: architecture-explainer
description: Explains your product's technical architecture in plain English — so you understand what's being built, can make informed decisions, and can describe it to others. Use when an agent has set up your tech stack and you're not sure how the pieces connect, or when you need to explain your system to a potential co-founder, investor, or hire. Produces an architecture-overview.md in plain language with a simple diagram.
phase: build
version: 1.0.0
---

# Architecture Explainer

## Quick Start

Say: **"Explain my architecture"** or **"Help me understand how this is built"**

Describe your stack or share your `stack-decision.md`. Total time: 10 minutes.
Output: `architecture-overview.md` — a plain-English explanation of how your system works, with a simple diagram and a glossary.

## What You'll Get

An `architecture-overview.md` with: a plain-English paragraph explaining how the system works, a simple flow diagram (text-based), what each component does in one sentence, what breaks if each component goes down, and a glossary of technical terms you'll hear repeatedly.

> **Example output excerpt:**
> **How it works in plain English:**
> When a user opens your app, their browser talks to Vercel, which runs your Next.js code. That code talks to Supabase to check if the user is logged in and fetch their data. Supabase stores all your data in a Postgres database — rows and columns, like a spreadsheet. When a user uploads a file, it goes to Supabase Storage (separate from the database). When someone pays, Stripe processes the transaction and tells your app "payment succeeded" via a webhook — a notification Stripe sends to your server.
> **The short version:** Browser → Vercel → Supabase (data + auth) + Stripe (payments). That's it.

## The Expert Judgment Embedded

This skill applies the **System Mental Model** approach — the idea that non-technical founders need to understand their architecture at the conceptual level, not the implementation level. You don't need to know how a database B-tree index works. You need to know that your database is where all your data lives, what happens if it goes down, and roughly how it connects to the rest of your system.

Understanding your architecture at this level lets you: make informed decisions when the agent asks what to do, evaluate trade-offs without needing to understand the code, onboard a technical hire faster, and describe your system credibly to investors or partners.

## The Process

### Step 1: Inventory Components

The agent asks you to share your stack (from `stack-decision.md` or by describing it). It maps every component into four categories:

| Category | What It Means | Example |
|----------|--------------|---------|
| **Frontend** | What the user sees in their browser | Next.js, your React components |
| **Backend** | The logic that runs on a server | Next.js API routes, Supabase Edge Functions |
| **Data** | Where information is stored | Supabase Postgres (database), Supabase Storage (files) |
| **Services** | Third-party tools your app relies on | Stripe (payments), Resend (email), PostHog (analytics) |

### Step 2: The Request Flow

The agent traces a "request" — what happens when a user does something — through your system:

1. User does X in the browser
2. Browser sends a request to Y
3. Y checks/stores data in Z
4. Response comes back to the browser
5. User sees the result

This is described in plain English, not code.

### Step 3: Failure Points

For each component, the agent explains what breaks if it goes down:
- "If Supabase goes down: users can't log in, no data loads, app is effectively down"
- "If Stripe goes down: existing users can use the app normally, but new signups can't pay"
- "If Vercel goes down: the app is completely inaccessible"

This gives you a realistic picture of dependencies and risk.

### Step 4: Glossary

Every technical term you'll encounter repeatedly is defined in one plain-English sentence. No jargon in the definition.

### Step 5: Output

`architecture-overview.md` — the plain-English explanation, ASCII flow diagram, component summary, failure analysis, and glossary. Save this. Update it when the stack changes.

## Worked Example

**Founder:** Has a Next.js + Supabase + Stripe + Resend stack for an agency client portal.

**Output:**
> **Architecture Overview — Agency Client Portal**
>
> **How it works (plain English):**
> Your product has four main pieces. Your **app** (Next.js on Vercel) is what users see — it's a website that runs both your marketing pages and the logged-in product. Your **database** (Supabase) is where everything is stored: user accounts, projects, files, comments. **Stripe** handles all money movement — when an agency signs up and pays, Stripe processes the card and tells your app "this person is now a paying customer." **Resend** sends emails — invites to clients, notifications when something needs approval.
>
> **How a request flows:**
> ```
> User's Browser
>       ↓ (opens the app)
>   Vercel (serves Next.js)
>       ↓ (needs user data)
>   Supabase (checks auth + fetches data)
>       ↓ (data returned)
>   Browser displays the project dashboard
>
> When a user uploads a file:
>   Browser → Vercel → Supabase Storage → File saved → URL returned → Browser shows preview
>
> When an agency pays:
>   Browser → Stripe Checkout (Stripe's page, not yours) → Payment processed
>   → Stripe sends webhook to Vercel → Your app marks the account as paid → Resend sends receipt
> ```
>
> **If each piece goes down:**
> | Component | What breaks |
> |-----------|-------------|
> | Vercel | Entire app inaccessible |
> | Supabase | Login fails, no data loads |
> | Stripe | Can't accept new payments (existing users unaffected) |
> | Resend | No emails sent (app still works) |
>
> **Glossary:**
> - **Webhook:** A notification Stripe (or any service) sends to your server when something happens — like a text message between servers
> - **API route:** A URL in your app that doesn't show a page — it does something (saves data, sends an email) and returns a response
> - **Row-level security:** A Supabase feature that makes the database enforce "User A can only see their own data" — your code doesn't have to check this manually
> - **Edge Function:** Code that runs on Supabase's servers (not your user's browser) — used for things that need to be kept secret or run server-side

## Related Skills

- Use **stack-selector** before this — the stack decision feeds into the architecture explanation
- Use **integration-picker** before this — integrations are the "services" layer of the architecture
- Use **founder-partner** when making architectural changes — the partner tracks how the system evolves over time

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

architecture-explainer

Directory Structure

SKILL.md

Report

Notice