How plankanban/planka works
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.