# jetbrains/kotlin-web-site architecture

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

- Interactive diagram: https://gitdiagram.com/jetbrains/kotlin-web-site
- Repository: https://github.com/jetbrains/kotlin-web-site

## Overview

##### Project Type and Purpose
- This is the source code for the Kotlin website (kotlinlang.org).
- It is a full-stack, largely static website generator combining:
- A Node/Next.js/React-based frontend for interactive pages and static generation
- A Python/Jinja2 backend for server‐side templating and routing
- A variety of build and content‐generation scripts (JS, Python)
- CI/CD configurations for GitHub Actions and TeamCity

##### High-Level Architecture Components
A. Frontend Layer
1. Next.js/React pages (pages/, blocks/, components/)
2. Webpack/Babel build process (webpack.config.js, .babelrc)
3. Static assets (static/js, static/css, public/images, assets/)
4. “next-dev” server for development and “next-build-static” for SSG

B. Backend Layer
1. Python server (kotlin-website.py and src/)
2. Jinja2 templates (templates/, including includes/, pages/, inc/)
3. Content repositories:
– docs/topics (Markdown docs for Kotlin)
– data/*.yml (site configuration, navigation trees, releases, events)
– external repositories (grammar generator, coroutines, Dokka, etc.)

C. Build & Content Generation
1. Node scripts (scripts/dist, scripts/react-renderer, scripts/latest-news)
2. Python scripts (scripts/*.py for geolocating events/universities)
3. PDF generation (scripts/pdf.sh, src/pdf.py)
4. Search index generation (scripts/dist/lib/search)
5. Docker build context (dockerfiles/, docker-compose.yml)

D. Testing & Quality
1. Playwright e2e & visual tests (playwright.config.js, test/e2e/)
2. Snapshot and component tests (test/page, test/component)
3. CI pipelines
– GitHub Actions (.github/workflows) for linting, data validation
– TeamCity (.teamcity/) for building site artifacts and docs

E. External Services
1. Google Geocoding API for event/university location scripts
2. Algolia or other search (scripts/dist/lib/search/algolia.ts)
3. External content repos (kotlinx.coroutines, Dokka, kotlin-spec, etc.)

##### Relationships and Data Flows
- Editor changes Markdown/YAML → Build scripts (Node/Python) parse content →
Jinja2 templates + React components → Static HTML/CSS/JS output
- Next.js SSG produces interactive React pages; Python server serves non-Next.js pages
- CI pipelines trigger build scripts → run tests → deploy static artifacts to CDN/web server
- Docker images built for local/static e2e testing (nginx, app server, Playwright)

##### Key Architectural Patterns and Principles
- Static Site Generation (SSG) with Incremental React hydration
- Template-Driven Content (Jinja2 for Markdown + YAML → HTML)
- Separation of Concerns
- Data (docs/, data/)
- Presentation (templates/, blocks/, components/)
- Build/Automation (scripts/, dockerfiles/)
- Testing (test/, playwright)
- CI/CD as code: workflows in GitHub Actions + Kotlin‐DSL for TeamCity

##### Detail Level
- Every distinct script cluster (e.g., scripts/dist, scripts/latest-news, scripts/stdlib) as sub‐components.
- Template includes and content directories feeding into Python’s rendering engine.
- Separate interactive pages (Next.js) from purely templated pages (Jinja2).
- Testing layer showing Playwright containers and test suites consuming deployed artifacts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Next.js/React Frontend"
        pages["pages/"]:::frontend
        blocks["blocks/"]:::frontend
        components["components/"]:::frontend
        webpack["webpack.config.js"]:::frontend
        nextcfg["next.config.js"]:::frontend
        assets["static/js/"]:::frontend
    end

    subgraph "Python/Jinja2 Backend"
        server["kotlin-website.py"]:::backend
        modules["src/"]:::backend
        templates["templates/"]:::backend
    end

    subgraph "Data/Content"
        docs["docs/topics/"]:::data
        datacfg["data/"]:::data
        external["external/"]:::data
    end

    subgraph "Build & Content Generation"
        subgraph "Node Scripts" 
            dist["scripts/dist/"]:::build
            reactrenderer["scripts/react-renderer/"]:::build
            news["scripts/latest-news/"]:::build
            stdlib["scripts/stdlib/"]:::build
            search["Search Index Generator"]:::build
        end
        subgraph "Python Scripts"
            evegeo["events_geolocator.py"]:::build
            unigeo["universities_geolocator.py"]:::build
            uggeo["user_groups_geolocator.py"]:::build
            pdfsh["scripts/pdf.sh"]:::build
            pdfpy["src/pdf.py"]:::build
        end
        docker["Docker Contexts"]:::build
    end

    subgraph "CI/CD"
        gha["GitHub Actions"]:::ci
        tc["TeamCity"]:::ci
    end

    subgraph "Testing & Quality"
        e2e["Playwright E2E Tests"]:::testing
        comp["Component Tests"]:::testing
        pageTest["Page Tests"]:::testing
    end

    %% Data to Build
    docs -->|feeds| dist
    docs -->|feeds| evegeo
    datacfg -->|feeds| reactrenderer
    datacfg -->|feeds| unigeo
    external -->|feeds| stdlib
    external -->|feeds| uggeo

    %% Build to Frontend/Backend
    dist -->|provides content| pages
    reactrenderer -->|renders React| components
    news -->|updates news| blocks
    stdlib -->|generates stdlib content| pages
    search -->|builds index| components
    evegeo -->|generates geo data| templates
    unigeo -->|generates geo data| templates
    uggeo -->|generates geo data| templates
    pdfsh -->|triggers| pdfpy

    %% CI/CD triggers
    gha -->|runs| dist
    gha -->|runs| evegeo
    tc -->|runs| search
    tc -->|runs| pdfsh

    %% Docker for e2e
    docker -->|provides env| e2e

    %% Testing consumes deployed
    pages -->|deployed| e2e
    server -->|deployed| e2e
    components -->|deployed| comp
    templates -->|deployed| pageTest

    %% Click Events
    click pages "https://github.com/jetbrains/kotlin-web-site/tree/master/pages/"
    click blocks "https://github.com/jetbrains/kotlin-web-site/tree/master/blocks/"
    click components "https://github.com/jetbrains/kotlin-web-site/tree/master/components/"
    click webpack "https://github.com/jetbrains/kotlin-web-site/blob/master/webpack.config.js"
    click nextcfg "https://github.com/jetbrains/kotlin-web-site/blob/master/next.config.js"
    click assets "https://github.com/jetbrains/kotlin-web-site/tree/master/static/js/"
    click server "https://github.com/jetbrains/kotlin-web-site/blob/master/kotlin-website.py"
    click modules "https://github.com/jetbrains/kotlin-web-site/tree/master/src/"
    click templates "https://github.com/jetbrains/kotlin-web-site/tree/master/templates/"
    click docs "https://github.com/jetbrains/kotlin-web-site/tree/master/docs/topics/"
    click datacfg "https://github.com/jetbrains/kotlin-web-site/tree/master/data/"
    click external "https://github.com/jetbrains/kotlin-web-site/tree/master/external/"
    click dist "https://github.com/jetbrains/kotlin-web-site/tree/master/scripts/dist/"
    click reactrenderer "https://github.com/jetbrains/kotlin-web-site/tree/master/scripts/react-renderer/"
    click news "https://github.com/jetbrains/kotlin-web-site/tree/master/scripts/latest-news/"
    click stdlib "https://github.com/jetbrains/kotlin-web-site/tree/master/scripts/stdlib/"
    click search "https://github.com/jetbrains/kotlin-web-site/tree/master/scripts/dist/lib/search/"
    click evegeo "https://github.com/jetbrains/kotlin-web-site/blob/master/scripts/events_geolocator.py"
    click unigeo "https://github.com/jetbrains/kotlin-web-site/blob/master/scripts/universities_geolocator.py"
    click uggeo "https://github.com/jetbrains/kotlin-web-site/blob/master/scripts/user_groups_geolocator.py"
    click pdfsh "https://github.com/jetbrains/kotlin-web-site/blob/master/scripts/pdf.sh"
    click pdfpy "https://github.com/jetbrains/kotlin-web-site/blob/master/src/pdf.py"
    click docker "https://github.com/jetbrains/kotlin-web-site/tree/master/dockerfiles/"
    click gha "https://github.com/jetbrains/kotlin-web-site/tree/master/.github/workflows/"
    click tc "https://github.com/jetbrains/kotlin-web-site/tree/master/.teamcity/"
    click e2e "https://github.com/jetbrains/kotlin-web-site/blob/master/playwright.config.js"
    click comp "https://github.com/jetbrains/kotlin-web-site/tree/master/test/component/"
    click pageTest "https://github.com/jetbrains/kotlin-web-site/tree/master/test/page/"

    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef build fill:#ffe5b4,stroke:#cc8400,color:#cc8400
    classDef data fill:#f0f0f0,stroke:#666666,color:#666666
    classDef ci fill:#e2e3ff,stroke:#4f42b5,color:#4f42b5
    classDef testing fill:#f8d7da,stroke:#721c24,color:#721c24
```
