# bluesky-social/atproto-website architecture

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

- Interactive diagram: https://gitdiagram.com/bluesky-social/atproto-website
- Repository: https://github.com/bluesky-social/atproto-website

## Overview

##### Project Type and Purpose
- Type: Static documentation website (Next.js + MDX)
- Purpose: Serve multilingual AT Protocol docs, specs, and guides at atproto.com

##### File Structure
- src/app/[locale] – App-Router pages and MDX content (file-based routing + i18n)
- src/components – Shared React components used in MDX layouts
- src/mdx – Custom MDX plugins (recma, rehype, remark, search indexing)
- src/styles, tailwind.config.ts, postcss.config.js – Styling pipeline (Tailwind CSS)
- public – Static assets (images, fonts)
- next.config.mjs, middleware.js – Next.js configuration & locale middleware

##### README for Insights
- Next dev/build commands, routing starts at src/app/[locale]/en.mdx
- MDX-driven content generation and automatic live reload

##### Main Components
a. Content Repository (GitHub)
– MDX files under src/app (articles, guides, specs)
– React components under src/components
– Styles + assets under src/styles & public
b. Build Pipeline
– npm install → Next.js build
– MDX loader + custom recma/rehype/remark plugins
– Tailwind CSS + PostCSS → CSS bundle
c. Next.js Runtime (App Router)
– File-based routing with dynamic [locale] segments
– getStaticProps-like SSG for MDX pages, fallback SSR if needed
– Middleware for locale redirects
d. Deployment & Hosting
– Output: static HTML, JSON, JS bundles in .next/
– Deployed to Vercel or similar CDN for global edge delivery
e. Client (Browser)
– Requests localized URL (e.g., /en/articles/why-atproto)
– Receives pre-rendered HTML + JS for hydration

##### Relationships & Interactions
- Developer → GitHub → CI/CD
↳ triggers Build Pipeline
- Build Pipeline
– Reads MDX + components + styles → Next.js build
– Produces static assets & serverless functions
- CDN / Edge Network
– Serves pre-rendered HTML, JSON routes, static assets
- Browser
– Fetches HTML → hydrates React components → interactive site

##### Architectural Patterns & Principles
- File-based routing (Next.js App Router)
- Static Site Generation (SSG) with optional SSR for dynamic content
- i18n using dynamic route segments + middleware redirect
- MDX as CMS: content-as-code pattern
- Component-driven design (design tokens in Tailwind + shared React UI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer triggers
    Dev["Developer"]:::actor
    GitHub[(Git Repository)]:::datastore
    CI["CI/CD Pipeline"]:::process

    Dev -->|push code to| GitHub
    GitHub -->|triggers| CI

    %% Content Repository
    subgraph "Content Repository"
        direction TB
        MDX["MDX Content\n(src/app/[locale])"]:::content
        ReactComp["React Components\n(src/components)"]:::content
        Icons["Shared Icons Set\n(src/components/icons)"]:::content
        StylesSrc["Base Styles\n(src/styles/tailwind.css)"]:::content
        Assets["Static Assets\n(public)"]:::content
    end

    %% MDX Plugin Pipeline
    subgraph "MDX Plugin Pipeline"
        direction TB
        Recma["recma Plugin\n(src/mdx/recma.mjs)"]:::process
        Rehype["rehype Plugin\n(src/mdx/rehype.mjs)"]:::process
        Remark["remark Plugin\n(src/mdx/remark.mjs)"]:::process
        Search["search Plugin\n(src/mdx/search.mjs)"]:::process
    end

    %% Styling Pipeline
    subgraph "Styling Pipeline"
        direction TB
        TailwindCfg["Tailwind Config\n(tailwind.config.ts)"]:::process
        PostCSSCfg["PostCSS Config\n(postcss.config.js)"]:::process
        StylesProc["CSS Processor"]:::process
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        Build["Next.js Build"]:::build
    end

    CI --> Build
    MDX --> Build
    ReactComp --> Build
    Icons --> Build
    Assets --> Build
    Recma --> Build
    Rehype --> Build
    Remark --> Build
    Search --> Build
    TailwindCfg --> StylesProc --> Build
    PostCSSCfg --> StylesProc

    %% Next.js Runtime
    subgraph "Next.js Runtime" 
        direction TB
        Routing["App Router\n(src/app/[locale])"]:::runtime
        Layouts["Layouts & Providers\n(layout.tsx, providers.tsx)"]:::runtime
        NotFound["Fallback Pages\n(not-found.tsx)"]:::runtime
        Middleware["Locale Middleware\n(src/middleware.js)"]:::runtime
        SSGSSR["SSG/SSR Serverless"]:::runtime
    end

    Build --> Routing
    Middleware --> Routing
    Layouts --> Routing
    NotFound --> Routing
    Routing --> SSGSSR

    %% Deployment / CDN
    subgraph "Deployment & CDN"
        direction TB
        CDN["CDN / Edge Network"]:::infra
        Output[".next Output"]:::infra
    end

    Build --> Output --> CDN
    SSGSSR --> CDN

    %% Client
    Browser["Client Browser"]:::client
    Browser -->|request page| CDN
    CDN -->|serve HTML+JS| Browser

    %% Click Events
    click MDX "https://github.com/bluesky-social/atproto-website/tree/main/src/app/[locale]"
    click ReactComp "https://github.com/bluesky-social/atproto-website/tree/main/src/components"
    click Icons "https://github.com/bluesky-social/atproto-website/tree/main/src/components/icons"
    click Recma "https://github.com/bluesky-social/atproto-website/blob/main/src/mdx/recma.mjs"
    click Rehype "https://github.com/bluesky-social/atproto-website/blob/main/src/mdx/rehype.mjs"
    click Remark "https://github.com/bluesky-social/atproto-website/blob/main/src/mdx/remark.mjs"
    click Search "https://github.com/bluesky-social/atproto-website/blob/main/src/mdx/search.mjs"
    click TailwindCfg "https://github.com/bluesky-social/atproto-website/blob/main/tailwind.config.ts"
    click PostCSSCfg "https://github.com/bluesky-social/atproto-website/blob/main/postcss.config.js"
    click StylesSrc "https://github.com/bluesky-social/atproto-website/blob/main/src/styles/tailwind.css"
    click Assets "https://github.com/bluesky-social/atproto-website/tree/main/public"
    click Middleware "https://github.com/bluesky-social/atproto-website/blob/main/src/middleware.js"
    click Routing "https://github.com/bluesky-social/atproto-website/tree/main/src/app/[locale]"
    click Layouts "https://github.com/bluesky-social/atproto-website/blob/main/src/app/[locale]/layout.tsx"
    click Layouts "https://github.com/bluesky-social/atproto-website/blob/main/src/app/[locale]/providers.tsx"
    click NotFound "https://github.com/bluesky-social/atproto-website/blob/main/src/app/[locale]/not-found.tsx"
    click GitHub "https://github.com/bluesky-social/atproto-website/blob/main/README.md"
    click GitHub "https://github.com/bluesky-social/atproto-website/tree/main/Makefile"
    click GitHub "https://github.com/bluesky-social/atproto-website/blob/main/next-env.d.ts"
    click GitHub "https://github.com/bluesky-social/atproto-website/blob/main/types.d.ts"
    click GitHub "https://github.com/bluesky-social/atproto-website/blob/main/tsconfig.json"

    %% Styles
    classDef content fill:#e2f7e2,stroke:#1e9c1e,color:#1e9c1e
    classDef process fill:#e2ebf7,stroke:#1e40af,color:#1e40af
    classDef build fill:#dbeafe,stroke:#1e3a8a,color:#1e3a8a
    classDef runtime fill:#f0f9ff,stroke:#0284c7,color:#0284c7
    classDef infra fill:#fff7ed,stroke:#ea580c,color:#ea580c
    classDef actor fill:#f3f4f6,stroke:#6b7280,color:#374151
    classDef client fill:#f9fafb,stroke:#4b5563,color:#111827
```
