# solana-foundation/developer-content architecture

> Architecture diagram of the GitHub repository solana-foundation/developer-content, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solana-foundation/developer-content
- Repository: https://github.com/solana-foundation/developer-content

## Overview

##### Project type and purpose
- This is a content‐service repo (“Solana Developer Content”) serving Markdown documentation, guides, courses, etc.
- It uses a Next.js (App Router) application to parse, index, and serve content via REST‐style API endpoints.
- The UI lives in a separate repo (solana-com) and calls these APIs.

##### File structure
- Top level: configuration (ESLint, Prettier, Husky), GitHub Actions, `.gitignore`, package manager files.
- `content/…` and `docs/…`: the raw Markdown content to be published.
- `code/…` and `contentlayer.config.ts`: code and config for Contentlayer (parsing Markdown into typed data).
- `src/app/api/...`: Next.js API routes (`/api/content`, `/api/nav`, `/api/paths`, `/api/overview`, `/api/records`) that expose structured content.
- `src/utils` and `src/types`: helper functions and shared type definitions.
- `src/components`, `src/app/page.tsx`: minimal preview UI for local development.
- `vercel.json` and `.github/workflows`: deployment to Vercel via GitHub Actions.

##### README for additional insights
- Confirms the repo is CONTENT ONLY, rendered by a separate UI repo.
- Setup: clone both repos, set `NEXT_PUBLIC_DEVELOPER_CONTENT_API_URL` to point at this app’s local server.
- Lists content categories (courses, docs, guides, resources).

##### Main components
A. Markdown Repositories
- “content/” directory (cookbook, guides, courses)
- “docs/” directory (core docs, RPC reference)
B. Content Parsing Layer
- Contentlayer (configured via `contentlayer.config.ts`)
- `code/` scripts (e.g., `cookbook` utilities, `coder.ts`)
- Custom parsers and helpers (`src/utils/parsers.ts`, `src/utils/records.ts`)
C. Next.js Application
- App Router
- API Routes under `src/app/api/*` that provide JSON endpoints
- Minimal preview pages/components (`HomeComponent.tsx`, `page.tsx`)
D. Deployment Pipeline
- GitHub Actions workflows (`.github/workflows/*.yml`) for formatting, building, deploying
- Vercel (configured via `vercel.json`)
E. External UI Consumer
- solana-com Frontend (separate repo) calling these APIs
F. Developer Workflow
- Local development: `pnpm install` → run Next.js dev server on port 3001
- UI dev: set `NEXT_PUBLIC_DEVELOPER_CONTENT_API_URL=http://localhost:3001`

##### Relationships and data flow
1. Authors commit Markdown to `content/` or `docs/`.
2. On build/dev server start, Contentlayer reads Markdown and generates in‐memory content nodes.
3. Next.js API routes import these nodes (using Contentlayer’s generated types) and respond to client requests.
4. External UI (solana-com) issues HTTP GET to endpoints like `/api/content/[slug]`, `/api/nav/[slug]`, etc.
5. Vercel hosts the Next.js app; GitHub Actions automate formatting, testing, and deployment.

##### Architectural patterns and design principles
- Headless CMS / Content API pattern
- File‐system routing (Next.js App Router)
- Separation of concerns: Markdown storage vs. parsing vs. serving vs. UI
- CI/CD via GitHub Actions + Vercel
- Type safety via Contentlayer and TypeScript

##### Essential details to capture
- Content directories vs. API routes
- Build vs. runtime phases
- How the external UI uses the API
- GitHub → Actions → Vercel path

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Markdown Storage
    subgraph "Markdown Storage" 
        direction TB
        ContentDir["content/ (cookbook, guides, courses)"]:::static
        DocsDir["docs/ (core docs, RPC reference)"]:::static
    end

    %% Content Parsing Layer
    subgraph "Content Parsing Layer"
        direction TB
        CLConfig["contentlayer.config.ts"]:::static
        CodeScripts["code/ (cookbook utils)"]:::static
        CoderScript["coder.ts"]:::static
        Parsers["src/utils/parsers.ts"]:::static
        RecordsUtil["src/utils/records.ts"]:::static
    end

    %% Next.js Application
    subgraph "Next.js Application (App Router)"
        direction TB
        Layout["layout.tsx"]:::service
        PreviewPage["page.tsx (Preview)"]:::service
        HomeComp["HomeComponent.tsx"]:::service
        APIContent["/api/content/[...slug]"]:::api
        APINav["/api/nav/[...slug]"]:::api
        APIOverview["/api/overview/[[...slug]]"]:::api
        APIPaths["/api/paths/[...slug]"]:::api
        APIRecords["/api/records/[...slug]"]:::api
    end

    %% External UI Consumer
    UIClient["solana-com Frontend UI"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GHWorkflows["GitHub Actions Workflows"]:::ci
        Vercel["Vercel (Deployment)"]:::ci
    end

    %% Relationships
    ContentDir -->|"ingest Markdown"| CLConfig
    DocsDir -->|"ingest Markdown"| CLConfig
    CLConfig -->|"configures"| CodeScripts
    CLConfig -->|"configures"| CoderScript
    CodeScripts -->|"use parsers"| Parsers
    CoderScript -->|"use records"| RecordsUtil

    Parsers -->|"generate content nodes"| Layout
    RecordsUtil -->|"generate content nodes"| Layout

    Layout --> PreviewPage
    PreviewPage --> HomeComp

    Layout --> APIContent
    Layout --> APINav
    Layout --> APIOverview
    Layout --> APIPaths
    Layout --> APIRecords

    UIClient -->|HTTP GET| APIContent
    UIClient -->|HTTP GET| APINav
    UIClient -->|HTTP GET| APIOverview
    UIClient -->|HTTP GET| APIPaths
    UIClient -->|HTTP GET| APIRecords

    GHWorkflows -->|build & deploy| Vercel
    Vercel -->|hosts| Layout

    %% Click Events
    click ContentDir "https://github.com/solana-foundation/developer-content/tree/main//content"
    click DocsDir "https://github.com/solana-foundation/developer-content/tree/main//docs"
    click CLConfig "https://github.com/solana-foundation/developer-content/blob/main//contentlayer.config.ts"
    click CodeScripts "https://github.com/solana-foundation/developer-content/tree/main//code/cookbook"
    click CoderScript "https://github.com/solana-foundation/developer-content/blob/main//coder.ts"
    click Parsers "https://github.com/solana-foundation/developer-content/blob/main/src/utils/parsers.ts"
    click RecordsUtil "https://github.com/solana-foundation/developer-content/blob/main/src/utils/records.ts"
    click Layout "https://github.com/solana-foundation/developer-content/blob/main/src/app/layout.tsx"
    click PreviewPage "https://github.com/solana-foundation/developer-content/blob/main/src/app/page.tsx"
    click HomeComp "https://github.com/solana-foundation/developer-content/blob/main/src/components/HomeComponent.tsx"
    click APIContent "https://github.com/solana-foundation/developer-content/blob/main/src/app/api/content/[...slug]/route.ts"
    click APINav "https://github.com/solana-foundation/developer-content/blob/main/src/app/api/nav/[...slug]/route.ts"
    click APIOverview "https://github.com/solana-foundation/developer-content/blob/main/src/app/api/overview/[[...slug]]/route.ts"
    click APIPaths "https://github.com/solana-foundation/developer-content/blob/main/src/app/api/paths/[...slug]/route.ts"
    click APIRecords "https://github.com/solana-foundation/developer-content/blob/main/src/app/api/records/[...slug]/route.ts"
    click GHWorkflows "https://github.com/solana-foundation/developer-content/blob/main//.github/workflows/contentlayer.yml"
    click Vercel "https://github.com/solana-foundation/developer-content/blob/main//vercel.json"

    %% Styles
    classDef static fill:#d0e7ff,stroke:#0284c7,color:#000
    classDef service fill:#d4f5d4,stroke:#059669,color:#000
    classDef api fill:#e2e8f0,stroke:#64748b,color:#000
    classDef external fill:#fde68a,stroke:#d97706,color:#000
    classDef ci fill:#f3d4fd,stroke:#9333ea,color:#000
```
