# lichess-org/api architecture

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

- Interactive diagram: https://gitdiagram.com/lichess-org/api
- Repository: https://github.com/lichess-org/api

## Overview

##### Main Components

a. Documentation Generation System
- OpenAPI Specification Files (in doc/specs/)
- Documentation Generator (Redocly, indicated by redocly.yaml)
- Static Documentation Output

b. Example Applications Layer
- OAuth App Examples
- Personal Token Examples
- Tournament Entry Examples

c. API Endpoints Categories (Group these by domain)
- Account Management
- Game Operations
- Tournament Systems
- Bot API
- User Management
- etc.

**┌─ Documentation Layer ─────────────────────┐**
- OpenAPI Specs → Redocly Generator → HTML  │
- ┬────────────────────────┘
- ↓
**┌─ API Interface Layer ────────────────────────────────┐**
- ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────────┐ │
- Account │ │  Games  │ │  Users  │ │ Challenges │ │
- ┘ └─────────┘ └─────────┘ └────────────┘ │
- ┬────────────────────────────────┘
- ↓
**┌─ Example Implementation Layer ──────────────┐**
- OAuth Apps | Personal Tokens | Demo Apps    │
- ┘

##### Important Elements to Highlight

a. Documentation Flow:
- How YAML specs are processed
- Validation steps (spectral, lint)
- Documentation generation process

b. API Organization:
- Related endpoints (use the folder structure in doc/specs/tags)
- Relationships between different API domains
- Authentication methods

c. Example Integration:
- How example apps connect to the API
- Demonstrate different auth flows

##### Additional Details

- A section showing the authentication flows (OAuth, Personal Token)
- Notes about rate limiting and API versioning
- Validation and testing flows

##### Specific Recommendations

- Numbered sequence indicators for flows
- API versioning information
- Security boundaries

##### Implementation Notes

- Clear separation between public and authenticated endpoints
- How the documentation integrates with the main Lichess platform
- Where example code fits into the overall architecture

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Documentation
        OpenAPI["OpenAPI Specification"]:::docs
        RedoclyGen["Redocly Generator"]:::docs
        DocOutput["Static Documentation"]:::docs
        Templates["Documentation Templates"]:::docs
        Schemas["API Schemas"]:::docs
        
        OpenAPI --> RedoclyGen
        Templates --> RedoclyGen
        Schemas --> RedoclyGen
        RedoclyGen --> DocOutput
    end

    subgraph "API Interface"
        Account["Account Management"]:::api
        Games["Game Operations"]:::api
        Users["User Management"]:::api
        Challenges["Challenge System"]:::api
        Bot["Bot API"]:::api
        Board["Board Operations"]:::api
        Teams["Team Management"]:::api
        Puzzles["Puzzle System"]:::api
        TV["TV/Streaming"]:::api
        Arena["Tournament Systems"]:::api
        OAuth["OAuth/Authentication"]:::api
    end

    subgraph "Example Applications"
        OAuthApp["OAuth App"]:::example
        OAuthBackend["OAuth Backend"]:::example
        PersonalToken["Personal Token Example"]:::example
        TournamentEntry["Tournament Entry Example"]:::example
    end

    subgraph "CI/CD"
        Lint["Linting Workflow"]:::cicd
        Publish["Publishing Workflow"]:::cicd
        
        Lint --> Publish
    end

    DocOutput --> Account
    DocOutput --> Games
    DocOutput --> Users
    DocOutput --> Challenges
    DocOutput --> Bot
    DocOutput --> Board
    DocOutput --> Teams
    DocOutput --> Puzzles
    DocOutput --> TV
    DocOutput --> Arena
    DocOutput --> OAuth

    OAuth --> OAuthApp
    OAuth --> OAuthBackend
    OAuth --> PersonalToken
    Arena --> TournamentEntry

    %% Click events for component mapping
    click OpenAPI "https://github.com/lichess-org/api/blob/master/doc/specs/lichess-api.yaml"
    click RedoclyGen "https://github.com/lichess-org/api/blob/master/doc/redocly.yaml"
    click Templates "https://github.com/lichess-org/api/blob/master/doc/template.hbs"
    click Schemas "https://github.com/lichess-org/api/tree/master/doc/specs/schemas/"
    click OAuthApp "https://github.com/lichess-org/api/tree/master/example/oauth-app/"
    click OAuthBackend "https://github.com/lichess-org/api/tree/master/example/oauth-backend/"
    click PersonalToken "https://github.com/lichess-org/api/tree/master/example/oauth-personal-token/"
    click TournamentEntry "https://github.com/lichess-org/api/tree/master/example/tournament-entry-code/"
    click Account "https://github.com/lichess-org/api/tree/master/doc/specs/tags/account/"
    click Games "https://github.com/lichess-org/api/tree/master/doc/specs/tags/games/"
    click Arena "https://github.com/lichess-org/api/tree/master/doc/specs/tags/arenatournaments/"
    click Bot "https://github.com/lichess-org/api/tree/master/doc/specs/tags/bot/"
    click Users "https://github.com/lichess-org/api/tree/master/doc/specs/tags/users/"
    click Challenges "https://github.com/lichess-org/api/tree/master/doc/specs/tags/challenges/"
    click Board "https://github.com/lichess-org/api/tree/master/doc/specs/tags/board/"
    click Teams "https://github.com/lichess-org/api/tree/master/doc/specs/tags/teams/"
    click Puzzles "https://github.com/lichess-org/api/tree/master/doc/specs/tags/puzzles/"
    click TV "https://github.com/lichess-org/api/tree/master/doc/specs/tags/tv/"
    click OAuth "https://github.com/lichess-org/api/tree/master/doc/specs/tags/oauth/"
    click Lint "https://github.com/lichess-org/api/blob/master/.github/workflows/lint.yml"
    click Publish "https://github.com/lichess-org/api/blob/master/.github/workflows/publish.yml"

    %% Styling
    classDef docs fill:#2374ab
    classDef api fill:#2a9d8f
    classDef example fill:#e76f51
    classDef cicd fill:#6c757d

    %% Legend
    Documentation:::docs
    API["API Interface"]:::api
    Examples["Example Apps"]:::example
    CICD["CI/CD"]:::cicd
```
