# aisflow/focalboard-ko architecture

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

- Interactive diagram: https://gitdiagram.com/aisflow/focalboard-ko
- Repository: https://github.com/aisflow/focalboard-ko

## Overview

##### Project Type and Purpose
- Focalboard is an open source, self‐hosted project management tool that can serve as an alternative to products like Trello, Notion, or Asana.
- It comes in two primary editions – a “Personal Desktop” (standalone desktop app for Windows, macOS, Linux) and a “Personal Server” (multi-user server deployment).
- The README clearly outlines deployment options (including Docker, cross-platform native desktop builds) along with developer and testing instructions.

##### File Structure and Key Components
- The repository is organized into multiple distinct areas:
- A “server” directory that contains Golang code (API endpoints, business logic, data models, services, SQL store implementations, migration scripts, WebSocket components, etc.). This represents the backend API and business logic layer.
- A “webapp” directory that houses a complete web client built with modern frontend tooling (ESLint, Cypress for testing, multiple React/TypeScript components, styles, assets, and i18n files). This is the client-facing SPA.
- “win-wpf”, “mac”, and “linux” directories indicate native desktop clients for each platform. They package the server (with an embedded SQLite store) to run locally as a personal desktop application.
- “docker” and “docker-testing” directories include Dockerfiles and docker-compose scripts, which illustrate how the system can be containerized.
- “import” folder contains various submodules (asana, jira, nextcloud-deck, notion, todoist, trello, etc.) that support data import from other popular project management or task-tracking tools.
- Additional directories like “docs”, “experiments”, and “website” provide documentation, developer guidance, and marketing/website content.
- There is clear separation of concerns with distinct folders for backend services, frontend interfaces, platform-specific app builds, and integrations.

##### Main Components
A. Backend Server (Golang):
- Components: API endpoints, authentication, business logic, WebSocket communication, data persistence modules (SQL store, migrations), and integrations (import services, telemetry, notifications).
- Subdirectories: “server/api”, “server/app”, “server/model”, “server/services”, “server/ws”, “server/utils”.
B. Frontend Web Application:
- Components: SPA application that interacts with the backend API, user interface components, client-side state management, and routing.
- Directory: “webapp” with its assets, components, and tests.
C. Desktop Clients:
- Three distinct builds are provided (Windows with win-wpf, macOS, and Linux).
- These apps package the server in a desktop context likely using an embedded database (SQLite).
D. Database / Data Store:
- Implemented via SQL store modules (under “server/services/store/sqlstore”) and migrations.
- Represents the persistence layer for both server and desktop deployments.
E. Integration / Import Services:
- Submodules under “import” allow syncing data from asana, jira, nextcloud, etc.
- These components interact with the backend to import data.
F. Docker and Deployment Infrastructure:
- Dockerfiles and Compose files (both in “docker” and “docker-testing”) show containerized builds, deployment strategies, and configuration details.
G. Documentation & Testing:
- “docs” and CI/CD workflows (in “.github/workflows” and “Makefile” scripts) support continuous integration and guidance for contributors.

##### Relationships and Data Flow
- The web client (in “webapp”) communicates with the backend server via REST API calls (and possibly via WebSockets from “server/ws”).
- Desktop apps also embed a version of the backend server to operate in a standalone mode with local data persistence.
- The backend exposes an API that serves data to both the web app and desktop apps.
- Import modules feed data into the system by interfacing with the backend’s import endpoints.
- Docker and CI/CD pipelines manage automated builds, tests, and deployments of both the server and web application.
- External integrations such as telemetry and notifications (under “server/services/telemetry” and “server/services/notify”) communicate with external services if needed.

##### Architectural Patterns / Design Principles
- Clear separation between client and server responsibilities (MVC or similar separation within the server).
- Use of micro-modules within the server (divided into API, app logic, services, models, and websockets) to encapsulate functionality.
- Multi-platform design: code is separated for desktop (native UI) and web app interfaces.
- Containerization for easier deployment and testing.
- Extensible design (via the “import” modules and plugin/delivery service structures).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Presentation Layer
    subgraph "Presentation Layer"
        webapp["Web Application (webapp)"]:::frontend
        subgraph "Desktop Clients"
            win["win-wpf (Windows)"]:::desktop
            mac["mac (macOS)"]:::desktop
            linux["linux (Linux)"]:::desktop
        end
    end

    %% Backend Server
    subgraph "Backend Server (Golang)"
        api["API Endpoints (server/api)"]:::backend
        app["Business Logic (server/app & server/model)"]:::backend
        ws["WebSocket (server/ws)"]:::backend
        services["Services (server/services)"]:::backend
        utils["Utilities (server/utils)"]:::backend
    end

    %% Data Persistence
    subgraph "Data Persistence"
        sqlstore["SQL Store (server/services/store/sqlstore)"]:::database
        migrations["Migrations (server/services/store/sqlstore/migrations)"]:::database
    end

    %% Integration Modules
    subgraph "Integration Modules"
        asana["Asana (import/asana)"]:::integration
        jira["Jira (import/jira)"]:::integration
        nextcloud["Nextcloud-Deck (import/nextcloud-deck)"]:::integration
        notion["Notion (import/notion)"]:::integration
        todoist["Todoist (import/todoist)"]:::integration
        trello["Trello (import/trello)"]:::integration
    end

    %% Deployment & DevOps
    subgraph "Deployment & DevOps"
        docker["Docker (docker)"]:::deployment
        dockerTesting["Docker Testing (docker-testing)"]:::deployment
        dockerfileBuild["Dockerfile.build"]:::deployment
        dockerfile["Dockerfile (docker/Dockerfile)"]:::deployment

        docs["Documentation (docs)"]:::docs
        workflows["CI/CD Workflows (.github/workflows)"]:::docs
        makefile["Makefile"]:::docs
    end

    %% Connections between Presentation and Backend
    webapp -->|"REST_API"| api
    win -->|"Embedded_API"| api
    mac -->|"Embedded_API"| api
    linux -->|"Embedded_API"| api

    %% Backend internal flows
    api -->|"Processes"| app
    api -->|"WS_Conn"| ws
    webapp -->|"RealTime_WS"| ws
    win -->|"RealTime_WS"| ws
    mac -->|"RealTime_WS"| ws
    linux -->|"RealTime_WS"| ws
    app -->|"Uses"| utils

    %% Backend to Data Persistence
    services -->|"Persists"| sqlstore
    sqlstore --> migrations

    %% Integration Modules to Backend
    asana -->|"Imports"| services
    jira -->|"Imports"| services
    nextcloud -->|"Imports"| services
    notion -->|"Imports"| services
    todoist -->|"Imports"| services
    trello -->|"Imports"| services

    %% Deployment & DevOps interactions
    docker -->|"Deploys"| api
    docker -->|"Deploys"| webapp
    dockerTesting -->|"Tests"| api
    dockerTesting -->|"Tests"| webapp
    makefile -->|"BuildTest"| api
    makefile -->|"BuildTest"| webapp
    workflows -->|"CI_CD"| api
    workflows -->|"CI_CD"| webapp

    %% Click Events
    click webapp "https://github.com/aisflow/focalboard-ko/tree/main/webapp"
    click win "https://github.com/aisflow/focalboard-ko/tree/main/win-wpf"
    click mac "https://github.com/aisflow/focalboard-ko/tree/main/mac"
    click linux "https://github.com/aisflow/focalboard-ko/tree/main/linux"
    click api "https://github.com/aisflow/focalboard-ko/tree/main/server/api"
    click app "https://github.com/aisflow/focalboard-ko/tree/main/server/app"
    click ws "https://github.com/aisflow/focalboard-ko/tree/main/server/ws"
    click services "https://github.com/aisflow/focalboard-ko/tree/main/server/services"
    click utils "https://github.com/aisflow/focalboard-ko/tree/main/server/utils"
    click sqlstore "https://github.com/aisflow/focalboard-ko/tree/main/server/services/store/sqlstore"
    click migrations "https://github.com/aisflow/focalboard-ko/tree/main/server/services/store/sqlstore/migrations"
    click asana "https://github.com/aisflow/focalboard-ko/tree/main/import/asana"
    click jira "https://github.com/aisflow/focalboard-ko/tree/main/import/jira"
    click nextcloud "https://github.com/aisflow/focalboard-ko/tree/main/import/nextcloud-deck"
    click notion "https://github.com/aisflow/focalboard-ko/tree/main/import/notion"
    click todoist "https://github.com/aisflow/focalboard-ko/tree/main/import/todoist"
    click trello "https://github.com/aisflow/focalboard-ko/tree/main/import/trello"
    click docker "https://github.com/aisflow/focalboard-ko/tree/main/docker"
    click dockerTesting "https://github.com/aisflow/focalboard-ko/tree/main/docker-testing"
    click dockerfileBuild "https://github.com/aisflow/focalboard-ko/blob/main/Dockerfile.build"
    click dockerfile "https://github.com/aisflow/focalboard-ko/tree/main/docker/Dockerfile"
    click docs "https://github.com/aisflow/focalboard-ko/tree/main/docs"
    click workflows "https://github.com/aisflow/focalboard-ko/tree/main/.github/workflows"
    click makefile "https://github.com/aisflow/focalboard-ko/tree/main/Makefile"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef desktop fill:#B8E4EA,stroke:#333,stroke-width:2px;
    classDef backend fill:#F9D6C1,stroke:#333,stroke-width:2px;
    classDef database fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef integration fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#C1F9C7,stroke:#333,stroke-width:2px;
    classDef docs fill:#F7C8E0,stroke:#333,stroke-width:2px;
```
