---
id: gh-convex-explain-app
name: "convex-explain-app"
url: https://skills.yangsir.net/skill/gh-convex-explain-app
author: convex
domain: ai-software-architecture-engineering
tags: ["convex", "codebase-explanation", "architecture-documentation", "data-model", "read-only"]
install_count: 34900
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-explain-app
---

# convex-explain-app

> 读取 Convex 应用的 schema 与函数导出面，输出数据模型与表间关系、公共/内部函数划分、认证与归属模型、已装组件与外部调用、1-2 条端到端请求数据流，全程只读。适合接手陌生项目、或在优化与自愈前先摸清现状的开发者，几分钟拿到可信的架构地图。

**Stats**: 34,900 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 摸清一个陌生 Convex 应用的架构

**Before**:

开发者接手一个陌生的 Convex 项目，只能逐个打开 schema.ts 和十几个函数文件，手工拼出表关系、公共与内部函数划分和鉴权方式，容易漏看或误判，往往要花一两个小时还不敢下结论。

**After**:

该 Skill 以 schema 与函数导出面为准据，一次输出表关系图、公共/内部函数清单、认证与归属模型、组件与外部边界以及端到端数据流，几分钟内即可得到可直接引用的架构地图。

| Metric | Before | After | Change |
|---|---|---|---|
| 摸清架构所需时间 | 90分钟 | 12分钟 | -87% |
| 被遗漏的公共接口数 | 8个 | 1个 | -88% |

## Readme

<!-- GENERATED from convex-agents content/capabilities/explain-app.json — do not edit by hand. -->

# Explain this Convex app

Before you can safely change an app you have to know what it is — and reading 15 function files top-to-bottom is slow and error-prone. This capability produces the map fast and accurately by reading the two sources that can't lie: the schema (the data model) and the function surface (`functionSpec` / the exported queries/mutations/actions). It is deliberately DESCRIPTIVE — it explains what IS, hands judgment to the audit capabilities and changes to the fixers. It is also the natural first step of an optimize or self-heal session, and the reusable 're-explain the current architecture' that 'change what you built' depends on.

## Workflow

1. DETECT the app: the `convex/` directory, `schema.ts`, and whether a deployment exists (if one does, `functionSpec`/`tables` via the official MCP give the authoritative live surface; if not, read the source directly). deploy-guard classifies any deployment read as read-only.
2. DATA MODEL: from `schema.ts`, list every table with its fields and, crucially, its RELATIONSHIPS — which `v.id("other")` fields point where, and which indexes exist (indexes reveal the intended access paths). Draw the foreign-key graph in words: 'tasks belong to projects (projectId) and users (ownerId); messages belong to conversations'.
3. FUNCTION SURFACE: enumerate every exported function, split PUBLIC (query/mutation/action — the attack/API surface) from INTERNAL (internalQuery/... — not client-reachable), and for each give a one-line 'what it does + what it touches'. The public/internal split is the single most important thing a newcomer needs and the thing source-skimming most often gets wrong.
4. AUTH / OWNERSHIP MODEL: state how identity is established (auth.config.ts provider? a users table keyed by tokenIdentifier?) and how ownership is enforced (is there a requireOwner-style check? which field is the owner?). Say plainly if there is NO auth foundation — that is load-bearing context for anyone about to change the app. (Describe the model; do not audit it for holes — that's convex-authz.)
5. COMPONENTS + EXTERNAL EDGES: list the `@convex-dev/*` components installed (convex.config.ts) and what they provide, the HTTP routes (http.ts) and crons, and any external calls in actions (which APIs, which env vars).
6. FLOW: trace 1-2 representative end-to-end paths ('client calls createTask → validates → inserts into tasks scoped to the caller → listMyTasks reads it back by the by_owner index') so the reader sees the moving parts connected, not just catalogued.
7. PRESENT as a scannable map (data model → public/internal functions → auth model → components/edges → a flow or two), accurate to the source. End by pointing at the next verbs: convex-reviewer/convex-authz to audit it, launch-readiness to score it, design/convex-expert to extend it. Never invent behavior the source doesn't show; if something is ambiguous, say so rather than guessing.

## Rules

- Read the schema + function surface (functionSpec/source) as the source of truth — never describe behavior the code doesn't show; flag ambiguity instead of guessing.
- Lead with the two things a newcomer most needs and skimming most often gets wrong: the data-model relationship graph and the public-vs-internal function split.
- State the auth/ownership model plainly, including 'there is no auth foundation' when that's the case — but DESCRIBE it; auditing it for holes is convex-authz's job.
- Descriptive, not evaluative: explain-app maps what IS and hands judgment to the audit capabilities and changes to the fixers.
- Read-only: any deployment introspection is read-only (deploy-guard); the app is not modified.
- End by pointing at the right next verb (audit → reviewer/authz, score → launch-readiness, extend → design/expert).


---
*Source: https://skills.yangsir.net/skill/gh-convex-explain-app*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-explain-app/markdown*