# railwayapp/docs architecture

> Architecture diagram of the GitHub repository railwayapp/docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/railwayapp/docs
- Repository: https://github.com/railwayapp/docs

## Overview

##### Project type and purpose
- This is a full-stack documentation site (“docs.railway.com”) built with Next.js and Contentlayer.
- Purpose: source markdown/MDX files under src/docs, generate static and dynamic doc pages, provide client-side search via a Meilisearch index, and serve everything on Railway.

##### File structure
- Top-level config & deployment
– .env.example, next.config.js, contentlayer.config.ts → Next/Contentlayer config
– meilisearch-docs-scraper.config.json → search‐index build config
– .github/workflows/ci.yml & build-search-index.yml → CI/CD pipelines
– railway.json → Railway deployment manifest
- Public assets
– public/ → images, fonts, static JSON for FAQs
- Source code
– src/pages → Next.js pages: static pages (index.tsx), dynamic routes ([...slug].tsx), API routes (pages/api/)
– src/components, layouts, mdxLayouts → reusable UI building blocks
– src/docs → markdown/MDX content for guides, tutorials, reference material
– src/hooks, utils, store → client‐side logic, state management, helper functions
- Build & styling
– tailwind.config.js, postcss.config.js, .babelrc.js → styling/build toolchain
– pnpm-lock.yaml, package.json → dependencies & scripts

##### Additional insights from README
- Next.js site, Node 18, uses pnpm
- Automatic deploys on Railway
- “build-search-index” workflow populates the search engine before deploy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Version Control
    Dev["Developer Local"]:::build
    Dev -->|push code| GitHub["GitHub Repo"]:::external

    %% Build Pipeline
    subgraph "Build Pipeline" 
        direction TB
        NextConfig["next.config.js"]:::build
        ContentlayerConfig["contentlayer.config.ts"]:::build
        MeiliConfig["meilisearch-docs-scraper.config.json"]:::build
        CI["GitHub Actions: CI (lint/test/build)"]:::build
        SearchIndex["GitHub Actions: build-search-index"]:::build
        NextConfig --> CI
        ContentlayerConfig --> CI
        CI --> Deploy
        MeiliConfig --> SearchIndex
        SearchIndex --> Meilisearch["Meilisearch Instance"]:::external
    end

    %% Deployment
    subgraph "Deployment" 
        direction TB
        Deploy["Railway Deploy"]:::external
        Railway["Railway Hosting"]:::runtime
        CI --> Deploy
        SearchIndex --> Deploy
        Deploy --> Railway
    end

    %% Runtime
    subgraph "Runtime" 
        direction TB
        Static["Static Files (SSG/ISR)"]:::runtime
        API["Serverless API Routes"]:::runtime
        Railway --> Static
        Railway --> API
        Client["Client Browser"]:::runtime
        Client -->|GET pages| Static
        Client -->|API call /api/search| API
        API -->|proxy query| Meilisearch
    end

    %% Click Events
    click NextConfig "https://github.com/railwayapp/docs/blob/main/next.config.js"
    click ContentlayerConfig "https://github.com/railwayapp/docs/blob/main/contentlayer.config.ts"
    click MeiliConfig "https://github.com/railwayapp/docs/blob/main/meilisearch-docs-scraper.config.json"
    click CI "https://github.com/railwayapp/docs/blob/main/.github/workflows/ci.yml"
    click SearchIndex "https://github.com/railwayapp/docs/blob/main/.github/workflows/build-search-index.yml"
    click Deploy "https://github.com/railwayapp/docs/blob/main/railway.json"

    %% Styles
    classDef build fill:#ade1f9,stroke:#333,stroke-width:1px
    classDef external fill:#f9d29d,stroke:#333,stroke-width:1px
    classDef runtime fill:#c8facc,stroke:#333,stroke-width:1px
```
