# plankanban/planka architecture

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

- Interactive diagram: https://gitdiagram.com/plankanban/planka
- Repository: https://github.com/plankanban/planka

## Overview

##### Project type and purpose
- Planka is a full-stack, open-source project‐tracking (Kanban) application.
- It has a React/Redux front end (“client/”), a Sails.js REST & WebSocket back end (“server/”), and a PostgreSQL database.
- It supports real-time updates (socket.io), file storage (local FS or S3), OIDC single-sign-on, notifications (email, Slack, Telegram, Google Chat, Webhooks), and can be deployed via Docker, Docker Compose, or Helm/Kubernetes.

##### File structure
- Top-level:
- client/ – React/Redux UI
- server/ – Sails.js API & business logic
- config/ – Docker, nginx, development configs
- charts/ – Helm chart for Kubernetes
- docker-compose*.yml – local dev and production orchestration
- Dockerfile(.base) – Docker images
- Patterns & frameworks:
- Front end: Redux-Saga for side effects, Redux-ORM for models, react-beautiful-dnd for drag-and-drop
- Back end: Sails.js MVC (controllers, models, helpers), Knex.js for migrations/seeds
- WebSockets: Sails sockets for real-time updates
- Hooks & policies: Sails lifecycle hooks for current user, file manager (Local/S3), OIDC, SMTP, S3, watcher
- External services: OIDC provider, email/notification services, file storage

##### Extract architecture details from README
- Tech stack: React, Redux, Redux-Saga, Redux-ORM, Semantic UI React, react-beautiful-dnd; Sails.js, Knex.js; PostgreSQL
- Features: Projects → Boards → Lists → Cards → Tasks, attachments, comments, due dates, time tracking, notifications, SSO

##### Main components and their interactions
a. User’s Browser (React client)
- Sends HTTP(S) REST requests to the Sails.js API
- Establishes a WebSocket (socket.io) connection for real-time events
- Interacts with Redux store, sagas, ORM models
b. Sails.js API Server
- Exposes REST endpoints (controllers in server/api/controllers/)
- Manages authentication & policies (is-authenticated, is-admin)
- Broadcasts events via WebSockets
- Orchestrates business logic in helpers and hooks
- Uses Knex.js to run database queries & migrations
- Stores uploaded files locally or to S3 via file-manager hook
- Sends outbound notifications (email, Slack, Telegram, Google Chat, Webhooks)
- Performs OIDC single-sign-on (exchange, token handling)
c. PostgreSQL Database
- Schemas defined by Knex migrations (server/db/migrations/)
- Data models (server/api/models and client/src/models mirror)
d. File Storage
- Local filesystem under server/private or S3 bucket
e. External Identity Provider (OIDC)
- For SSO login/exchange
f. Notification Services
- SMTP, Slack, Telegram, Google Chat, Webhooks
g. Deployment & Infrastructure
- Docker images (Dockerfile, Dockerfile.base)
- Docker Compose for dev & staging
- Helm chart (charts/planka/) for Kubernetes
- Healthcheck script, start.sh entrypoint
- CI/CD workflows (.github/workflows/) build, push, test, release

##### Architectural patterns & design principles
- Clear separation of concerns: UI ↔ API ↔ Persistence
- MVC on the server, modular controllers & helpers
- Redux-Saga for side-effects & async flows on the client
- Redux-ORM for normalized client models
- WebSocket pub/sub for real-time synchronization
- Pluggable hooks for file management & authentication
- Infrastructure as code via Docker & Helm

##### Be comprehensive
- Every key element: UI modules, API controllers, DB migrations, hooks, external integrations, deployment configs
- Don’t worry about drawing every single file—focus on logical groupings (e.g., “Controllers”, “Helpers”, “Policies”).
- Provide enough detail so a new engineer can understand data flow, integration points, and deployment topology at a glance.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        ReactClient["React Client Application"]:::frontend
        ReduxStore["Redux Store Configuration"]:::frontend
        ReduxSaga["Redux-Saga Side Effects"]:::frontend
        ReduxORM["Redux-ORM Client Models"]:::frontend
        UIComponents["React UI Components"]:::frontend
        APIModule["HTTP API Module"]:::frontend
        Styling["Semantic UI & Styling"]:::frontend
    end

    %% API Tier
    subgraph "API Tier"
        direction TB
        SailsServer["Sails.js API Server"]:::backend
        Controllers["REST Controllers"]:::backend
        Helpers["Business Logic Helpers"]:::backend
        Hooks["Sails Lifecycle Hooks"]:::backend
        Policies["Access Policies"]:::backend
        WSConfig["WebSocket Configuration"]:::backend
        DBConfig["Database Connection Config"]:::backend
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        PostgresDB["PostgreSQL Database"]:::persistence
        Migrations["Knex.js Migrations"]:::persistence
        Seeds["Database Seeds"]:::persistence
        FileStorage["Local File Storage"]:::persistence
    end

    %% External Services Tier
    subgraph "External Services"
        direction TB
        OIDC["OIDC Provider"]:::external
        Notifications["Notification Services"]:::external
    end

    %% Deployment Tier
    subgraph "Deployment & Infra"
        direction TB
        DockerBase["Docker Base Image"]:::deployment
        AppDockerfile["Application Dockerfile"]:::deployment
        DockerCompose["Docker Compose"]:::deployment
        HelmChart["Helm Chart for Kubernetes"]:::deployment
        Healthcheck["Healthcheck Script"]:::deployment
        Entrypoint["Container Entrypoint Script"]:::deployment
        CICD["CI/CD Workflows"]:::deployment
        ConfigTemplates["Project-wide Configuration Templates"]:::deployment
    end

    %% Connections - Client to API
    ReactClient -->|REST API| SailsServer
    ReactClient <-->|"WebSocket (socket.io)"| SailsServer
    ReactClient --> ReduxStore
    ReduxStore --> ReduxSaga
    ReduxStore --> ReduxORM
    ReactClient --> UIComponents
    ReactClient --> APIModule
    UIComponents --> Styling

    %% Connections - API Internal
    SailsServer --> Controllers
    SailsServer --> Helpers
    SailsServer --> Hooks
    SailsServer --> Policies
    SailsServer --> WSConfig
    SailsServer --> DBConfig

    %% Connections - API to Data
    Controllers --> PostgresDB
    Helpers --> Migrations
    Helpers --> Seeds
    Hooks --> FileStorage

    %% Connections - API to External
    SailsServer --> OIDC
    SailsServer --> Notifications

    %% Connections - Deployment
    SailsServer --> DockerBase
    DockerBase --> AppDockerfile
    AppDockerfile --> DockerCompose
    DockerCompose --> HelmChart
    DockerCompose --> Healthcheck
    DockerCompose --> Entrypoint
    CICD --> DockerBase
    CICD --> DockerCompose
    ConfigTemplates --> DockerCompose
    ConfigTemplates --> HelmChart

    %% Click Events
    click ReactClient "https://github.com/plankanban/planka/tree/master/client/"
    click ReduxStore "https://github.com/plankanban/planka/blob/master/client/src/store.js"
    click ReduxSaga "https://github.com/plankanban/planka/tree/master/client/src/sagas/"
    click ReduxORM "https://github.com/plankanban/planka/tree/master/client/src/models/"
    click UIComponents "https://github.com/plankanban/planka/tree/master/client/src/components/"
    click APIModule "https://github.com/plankanban/planka/tree/master/client/src/api/"
    click Styling "https://github.com/plankanban/planka/tree/master/client/src/assets/"
    click SailsServer "https://github.com/plankanban/planka/tree/master/server/"
    click Controllers "https://github.com/plankanban/planka/tree/master/server/api/controllers/"
    click Helpers "https://github.com/plankanban/planka/tree/master/server/api/helpers/"
    click Hooks "https://github.com/plankanban/planka/tree/master/server/api/hooks/"
    click Policies "https://github.com/plankanban/planka/tree/master/server/api/policies/"
    click WSConfig "https://github.com/plankanban/planka/blob/master/server/config/sockets.js"
    click DBConfig "https://github.com/plankanban/planka/blob/master/server/config/datastores.js"
    click Migrations "https://github.com/plankanban/planka/tree/master/server/db/migrations/"
    click Seeds "https://github.com/plankanban/planka/blob/master/server/db/seeds/default.js"
    click FileStorage "https://github.com/plankanban/planka/tree/master/server/private/attachments/"
    click LocalFileManager "https://github.com/plankanban/planka/blob/master/server/api/hooks/file-manager/LocalFileManager.js"
    click S3FileManager "https://github.com/plankanban/planka/blob/master/server/api/hooks/file-manager/S3FileManager.js"
    click OIDC "https://github.com/plankanban/planka/blob/master/server/api/hooks/oidc/index.js"
    click SMTP "https://github.com/plankanban/planka/blob/master/server/api/hooks/smtp/index.js"
    click Notifications "https://github.com/plankanban/planka/blob/master/server/api/helpers/utils/send-*.js"
    click DockerBase "https://github.com/plankanban/planka/blob/master/Dockerfile.base"
    click AppDockerfile "https://github.com/plankanban/planka/tree/master/Dockerfile"
    click DockerCompose "https://github.com/plankanban/planka/blob/master/docker-compose.yml"
    click HelmChart "https://github.com/plankanban/planka/tree/master/charts/planka/"
    click Healthcheck "https://github.com/plankanban/planka/blob/master/healthcheck.js"
    click Entrypoint "https://github.com/plankanban/planka/blob/master/start.sh"
    click CICD "https://github.com/plankanban/planka/tree/master/.github/workflows/"
    click ConfigTemplates "https://github.com/plankanban/planka/blob/master/config/development/nginx.conf"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef persistence fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#383d41,color:#383d41;
    classDef deployment fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
```
