# shadcn-ui/taxonomy architecture

> Architecture diagram of the GitHub repository shadcn-ui/taxonomy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shadcn-ui/taxonomy
- Repository: https://github.com/shadcn-ui/taxonomy

## Overview

#### Purpose and runtime
Taxonomy is an archived Next.js 13 reference application demonstrating App Router layouts, Server/Client Components, authentication, subscription billing, CRUD content, and MDX publishing. It runs as a TypeScript Next.js application; the root shell is `app/layout.tsx`, with request gating in `middleware.ts`.

#### Route domains and entry points
Route groups separate independent site experiences without changing URLs:
- Marketing and blog: `app/(marketing)/page.tsx`, `app/(marketing)/blog/[...slug]/page.tsx`, `app/(marketing)/[...slug]/page.tsx`.
- Public docs/guides: `app/(docs)/docs/[[...slug]]/page.tsx`, `app/(docs)/guides/[...slug]/page.tsx`.
- Auth: `app/(auth)/login/page.tsx`, `app/(auth)/register/page.tsx`.
- Authenticated product areas: `app/(dashboard)/dashboard/page.tsx`, `app/(editor)/editor/[postId]/page.tsx`.

Nested layouts establish domain-specific navigation and access-oriented UI: `app/(dashboard)/dashboard/layout.tsx`, `app/(editor)/editor/layout.tsx`, and `app/(marketing)/layout.tsx`.

#### Identity and authorization
NextAuth is exposed through the App Router handler at `app/api/auth/[...nextauth]/_route.ts`; a legacy Pages Router counterpart remains at `pages/api/auth/[...nextauth].ts`. Authentication configuration and session access are centralized in `lib/auth.ts` and `lib/session.ts`. `middleware.ts` is the request boundary for route-level protection/redirect behavior, while dashboard/editor pages and API handlers enforce user-scoped operations.

#### Application data and post lifecycle
Prisma is the persistence boundary, configured by `prisma/schema.prisma` and instantiated through `lib/db.ts`, targeting PlanetScale per project documentation. Posts flow from dashboard/editor UI into REST-style route handlers:
- Collection creation/listing: `app/api/posts/route.ts`
- Per-post read/update/delete: `app/api/posts/[postId]/route.ts`
- Editor experience: `components/editor.tsx`, `app/(editor)/editor/[postId]/page.tsx`

Zod validation contracts at `lib/validations/post.ts` and `lib/validations/user.ts` constrain inbound mutations before database access.

#### Subscription and billing boundary
Stripe integration is isolated behind `lib/stripe.ts` and subscription interpretation in `lib/subscription.ts`. The billing UI is `app/(dashboard)/dashboard/billing/page.tsx`; checkout/customer-portal-oriented user operations use `app/api/users/stripe/route.ts`. Stripe sends authoritative subscription changes to `app/api/webhooks/stripe/route.ts`, which updates Prisma-backed user/subscription state rather than trusting browser-side billing status.

#### Content publishing and rendering
Versioned MDX files are the source for documentation, guides, blog posts, and legal/marketing pages under `content/docs`, `content/guides`, `content/blog`, and `content/pages`. `contentlayer.config.js` builds these into typed consumable content; catch-all routes resolve slugs and render the appropriate collection. MDX rendering/presentation is shared through `components/mdx-components.tsx` and `components/mdx-card.tsx`, separating filesystem-authored public content from database-authored editor posts.

#### Presentation, metadata, and external delivery
Tailwind CSS and Radix-based primitives compose the UI, with global and MDX/editor styling in `styles/globals.css`, `styles/mdx.css`, and `styles/editor.css`. Dynamic social images are generated at the edge-compatible route `app/api/og/route.tsx`, validated by `lib/validations/og.ts`. Search-engine directives originate from `app/robots.ts`. External material services are NextAuth providers/email authentication, PlanetScale via Prisma, Stripe webhooks/APIs, and Vercel OG rendering.

Main entry points: [`app/api/posts/route.ts`](https://github.com/shadcn-ui/taxonomy/blob/main/app/api/posts/route.ts) (Post APIs), [`lib/db.ts`](https://github.com/shadcn-ui/taxonomy/blob/main/lib/db.ts) (Prisma data access), [`app/layout.tsx`](https://github.com/shadcn-ui/taxonomy/blob/main/app/layout.tsx) (App root shell), [`contentlayer.config.js`](https://github.com/shadcn-ui/taxonomy/blob/main/contentlayer.config.js) (Contentlayer build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public content"]
  node_marketing["Marketing &amp; blog routes<br/>public route domain<br/>[page.tsx]"]
  node_docs["Docs &amp; guides routes<br/>MDX route domain<br/>[page.tsx]"]
  node_mdxsource["Versioned MDX content<br/>filesystem content"]
  node_contentlayer{{"Contentlayer build<br/>content compiler"}}
  node_mdxui["MDX presentation<br/>shared components<br/>[mdx-components.tsx]"]
end

subgraph group_product["Product &amp; identity"]
  node_middleware{{"Request gate<br/>Next.js middleware<br/>[middleware.ts]"}}
  node_authroutes["Login &amp; register<br/>auth routes<br/>[page.tsx]"]
  node_authhandler{{"NextAuth handler<br/>App Router API<br/>[_route.ts]"}}
  node_authcore["Auth &amp; session core<br/>identity service<br/>[auth.ts]"]
  node_dashboard["Dashboard<br/>authenticated route domain<br/>[page.tsx]"]
  node_editor["Post editor<br/>authenticated route<br/>[page.tsx]"]
  node_editorui["Editor component<br/>client component<br/>[editor.tsx]"]
end

subgraph group_data["Data &amp; billing"]
  node_postsapi{{"Post APIs<br/>REST route handlers<br/>[route.ts]"}}
  node_validation["Mutation validation<br/>Zod contracts<br/>[post.ts]"]
  node_prisma[("Prisma data access<br/>database client<br/>[db.ts]")]
  node_planetscale[("PlanetScale<br/>managed database")]
  node_billing["Billing UI &amp; API<br/>subscription flow<br/>[page.tsx]"]
  node_stripe["Stripe integration<br/>billing service<br/>[stripe.ts]"]
  node_webhook{{"Stripe webhook<br/>authoritative event handler<br/>[route.ts]"}}
end

subgraph group_platform["Delivery &amp; metadata"]
  node_og{{"Social image API<br/>edge image route<br/>[route.tsx]"}}
  node_robots["Robots directives<br/>metadata route<br/>[robots.ts]"]
end

node_root["App root shell<br/>Next.js layout<br/>[layout.tsx]"]

node_root -->|"hosts"| node_marketing
node_root -->|"hosts"| node_docs
node_root -->|"hosts"| node_authroutes
node_middleware -->|"guards"| node_dashboard
node_middleware -->|"guards"| node_editor
node_authroutes -->|"sign-in requests"| node_authhandler
node_authhandler -->|"uses"| node_authcore
node_authcore -->|"loads users and sessions"| node_prisma
node_mdxsource -->|"compiled by"| node_contentlayer
node_contentlayer -->|"blog and pages"| node_marketing
node_contentlayer -->|"docs and guides"| node_docs
node_mdxui -->|"renders MDX"| node_marketing
node_mdxui -->|"renders MDX"| node_docs
node_dashboard -->|"manages posts"| node_postsapi
node_editor -->|"hosts"| node_editorui
node_editorui -->|"reads and mutates"| node_postsapi
node_postsapi -->|"validates input"| node_validation
node_postsapi -->|"user-scoped CRUD"| node_prisma
node_prisma -->|"persists to"| node_planetscale
node_billing -->|"starts billing operations"| node_stripe
node_webhook -->|"receives events from"| node_stripe
node_webhook -->|"updates subscriptions"| node_prisma
node_og -->|"validates image input"| node_validation

click node_root "https://github.com/shadcn-ui/taxonomy/blob/main/app/layout.tsx"
click node_middleware "https://github.com/shadcn-ui/taxonomy/blob/main/middleware.ts"
click node_marketing "https://github.com/shadcn-ui/taxonomy/blob/main/app/(marketing)/page.tsx"
click node_docs "https://github.com/shadcn-ui/taxonomy/blob/main/app/(docs)/docs/%5B%5B...slug%5D%5D/page.tsx"
click node_mdxsource "https://github.com/shadcn-ui/taxonomy/tree/main/content/docs"
click node_contentlayer "https://github.com/shadcn-ui/taxonomy/blob/main/contentlayer.config.js"
click node_mdxui "https://github.com/shadcn-ui/taxonomy/blob/main/components/mdx-components.tsx"
click node_authroutes "https://github.com/shadcn-ui/taxonomy/blob/main/app/(auth)/login/page.tsx"
click node_authhandler "https://github.com/shadcn-ui/taxonomy/blob/main/app/api/auth/%5B...nextauth%5D/_route.ts"
click node_authcore "https://github.com/shadcn-ui/taxonomy/blob/main/lib/auth.ts"
click node_dashboard "https://github.com/shadcn-ui/taxonomy/blob/main/app/(dashboard)/dashboard/page.tsx"
click node_editor "https://github.com/shadcn-ui/taxonomy/blob/main/app/(editor)/editor/%5BpostId%5D/page.tsx"
click node_editorui "https://github.com/shadcn-ui/taxonomy/blob/main/components/editor.tsx"
click node_postsapi "https://github.com/shadcn-ui/taxonomy/blob/main/app/api/posts/route.ts"
click node_validation "https://github.com/shadcn-ui/taxonomy/blob/main/lib/validations/post.ts"
click node_prisma "https://github.com/shadcn-ui/taxonomy/blob/main/lib/db.ts"
click node_billing "https://github.com/shadcn-ui/taxonomy/blob/main/app/(dashboard)/dashboard/billing/page.tsx"
click node_stripe "https://github.com/shadcn-ui/taxonomy/blob/main/lib/stripe.ts"
click node_webhook "https://github.com/shadcn-ui/taxonomy/blob/main/app/api/webhooks/stripe/route.ts"
click node_og "https://github.com/shadcn-ui/taxonomy/blob/main/app/api/og/route.tsx"
click node_robots "https://github.com/shadcn-ui/taxonomy/blob/main/app/robots.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_marketing,node_docs,node_mdxsource,node_contentlayer,node_mdxui toneBlue
class node_middleware,node_authroutes,node_authhandler,node_authcore,node_dashboard,node_editor,node_editorui toneAmber
class node_postsapi,node_validation,node_prisma,node_planetscale,node_billing,node_stripe,node_webhook toneMint
class node_og,node_robots toneRose
class node_root toneNeutral
```

## Components

### Public content

- [Marketing & blog routes](https://github.com/shadcn-ui/taxonomy/blob/main/app/(marketing)/page.tsx): public route domain · `app/(marketing)/page.tsx`
- [Docs & guides routes](https://github.com/shadcn-ui/taxonomy/blob/main/app/(docs)/docs/%5B%5B...slug%5D%5D/page.tsx): MDX route domain · `app/(docs)/docs/[[...slug]]/page.tsx`
- [Versioned MDX content](https://github.com/shadcn-ui/taxonomy/tree/main/content/docs): filesystem content · Docs, guides, blog, and marketing pages. · `content/docs`
- [Contentlayer build](https://github.com/shadcn-ui/taxonomy/blob/main/contentlayer.config.js): content compiler · `contentlayer.config.js`
- [MDX presentation](https://github.com/shadcn-ui/taxonomy/blob/main/components/mdx-components.tsx): shared components · `components/mdx-components.tsx`

### Product & identity

- [Request gate](https://github.com/shadcn-ui/taxonomy/blob/main/middleware.ts): Next.js middleware · Protects and redirects route requests. · `middleware.ts`
- [Login & register](https://github.com/shadcn-ui/taxonomy/blob/main/app/(auth)/login/page.tsx): auth routes · `app/(auth)/login/page.tsx`
- [NextAuth handler](https://github.com/shadcn-ui/taxonomy/blob/main/app/api/auth/%5B...nextauth%5D/_route.ts): App Router API · `app/api/auth/[...nextauth]/_route.ts`
- [Auth & session core](https://github.com/shadcn-ui/taxonomy/blob/main/lib/auth.ts): identity service · `lib/auth.ts`
- [Dashboard](https://github.com/shadcn-ui/taxonomy/blob/main/app/(dashboard)/dashboard/page.tsx): authenticated route domain · `app/(dashboard)/dashboard/page.tsx`
- [Post editor](https://github.com/shadcn-ui/taxonomy/blob/main/app/(editor)/editor/%5BpostId%5D/page.tsx): authenticated route · `app/(editor)/editor/[postId]/page.tsx`
- [Editor component](https://github.com/shadcn-ui/taxonomy/blob/main/components/editor.tsx): client component · `components/editor.tsx`

### Data & billing

- [Post APIs](https://github.com/shadcn-ui/taxonomy/blob/main/app/api/posts/route.ts): REST route handlers · Collection and per-post CRUD endpoints. · `app/api/posts/route.ts`
- [Mutation validation](https://github.com/shadcn-ui/taxonomy/blob/main/lib/validations/post.ts): Zod contracts · `lib/validations/post.ts`
- [Prisma data access](https://github.com/shadcn-ui/taxonomy/blob/main/lib/db.ts): database client · `lib/db.ts`
- **PlanetScale**: managed database
- [Billing UI & API](https://github.com/shadcn-ui/taxonomy/blob/main/app/(dashboard)/dashboard/billing/page.tsx): subscription flow · Checkout and customer portal operations. · `app/(dashboard)/dashboard/billing/page.tsx`
- [Stripe integration](https://github.com/shadcn-ui/taxonomy/blob/main/lib/stripe.ts): billing service · API client and subscription interpretation. · `lib/stripe.ts`
- [Stripe webhook](https://github.com/shadcn-ui/taxonomy/blob/main/app/api/webhooks/stripe/route.ts): authoritative event handler · `app/api/webhooks/stripe/route.ts`

### Delivery & metadata

- [Social image API](https://github.com/shadcn-ui/taxonomy/blob/main/app/api/og/route.tsx): edge image route · `app/api/og/route.tsx`
- [Robots directives](https://github.com/shadcn-ui/taxonomy/blob/main/app/robots.ts): metadata route · `app/robots.ts`

### Other components

- [App root shell](https://github.com/shadcn-ui/taxonomy/blob/main/app/layout.tsx): Next.js layout · `app/layout.tsx`

## Connections

- App root shell → Marketing & blog routes: hosts
- App root shell → Docs & guides routes: hosts
- App root shell → Login & register: hosts
- Request gate → Dashboard: guards
- Request gate → Post editor: guards
- Login & register → NextAuth handler: sign-in requests
- NextAuth handler → Auth & session core: uses
- Auth & session core → Prisma data access: loads users and sessions
- Versioned MDX content → Contentlayer build: compiled by
- Contentlayer build → Marketing & blog routes: blog and pages
- Contentlayer build → Docs & guides routes: docs and guides
- MDX presentation → Marketing & blog routes: renders MDX
- MDX presentation → Docs & guides routes: renders MDX
- Dashboard → Post APIs: manages posts
- Post editor → Editor component: hosts
- Editor component → Post APIs: reads and mutates
- Post APIs → Mutation validation: validates input
- Post APIs → Prisma data access: user-scoped CRUD
- Prisma data access → PlanetScale: persists to
- Billing UI & API → Stripe integration: starts billing operations
- Stripe webhook → Stripe integration: receives events from
- Stripe webhook → Prisma data access: updates subscriptions
- Social image API → Mutation validation: validates image input
