# zasper-io/zasper architecture

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

- Interactive diagram: https://gitdiagram.com/zasper-io/zasper
- Repository: https://github.com/zasper-io/zasper

## Overview

##### Main Components
- Frontend/UI: Represented by the “ui” directory which includes React/TypeScript code, styles, assets, and supporting files. This layer is responsible for the interactive components like the editor, terminal, launcher, command palette, file explorer, and status bar.
- Backend/API Server: The Go code at the root (such as app.go, spa.go, and spa_apiserver.go) handles REST API endpoints and serves the frontend. It also includes HTTP-related logic (see the “http” directory) and health checks (“health”).
- Content and Notebook Management: The “content” directory manages notebook files, payloads, and content watching – analogous to document or content management for notebooks.
- Kernel and Kernel Sessions: The “kernel” and “kernelspec” directories encapsulate the logic for handling kernel communication, launching, session management, and supervision. They implement features for communication between front-end notebook cells and the running kernels.
- GitClient Integration: The “gitclient” directory manages git-related operations, indicating built-in version control capabilities.
- Session Handling and Core Services: The “core” directory provides essential utilities such as configuration, database interfacing, and session management. Other folders like “session” round out the session API and management functions.
- WebSocket Communication: The “websocket” directory suggests real-time communication links for features such as terminal interactions or kernel event streaming.
- Deployment and CI/CD: Directories like “docker”, “.github”, and associated CI workflow files indicate how the project is built, deployed, and tested.

##### Relationships and Interactions
- The Frontend (UI) sends REST API calls to the backend, primarily to initiate or manage notebook sessions, file operations, or kernel interactions.
- The API layer forwards these interactions to specialized modules—for example, the “kernel” package for kernel sessions, the “content” package for file/notebook management, and “session” for user or process sessions.
- Real-time communication (via WebSocket endpoints) enables interactive terminal sessions and live updates from kernels.
- Git operations are handled separately in the “gitclient” module and are likely triggered by UI events on the version control interface.
- The backend interacts with core components (such as configuration and database modules in “core”) to maintain state, persistence, and application configuration.
- Docker build files and GitHub workflows illustrate that the system can be containerized and supports continuous integration/deployment.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system clearly divides responsibilities between frontend and backend, with dedicated packages for kernel management, content handling, session management, and Git integration.
- Modular Structure: Each domain (e.g., kernel, content, git, session) is handled in its own directory, simplifying maintenance and potential scalability.
- Concurrency Focus: The use of Go and specialized modules (like “kernel/launcher”, “kernel/connection”, “kernel/kernel_supervisor”) highlights a design optimized for handling multiple concurrent processes and real-time communication.
- Support for Extensibility: The design anticipates future kernels and possible additional frontend integrations (as suggested by the README and roadmap).

##### Final Elements
- Clear labels for each component (e.g., "UI – Notebook Editor", "Kernel Manager", "Content API", "Git Client", "Session Manager", "WebSockets Handler").
- Legends or annotations to capture important details such as the role of concurrency in Go’s design or the support for multiple kernel types.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Frontend/UI (React/Electron)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["Backend/API Server (Go)"]:::backend
        KernelManager["Kernel Manager"]:::backend
        KernelSpec["Kernel Specs"]:::backend
        Content["Content Manager"]:::backend
        Core["Core Services"]:::backend
        Session["Session Manager"]:::backend
        Git["GitClient Integration"]:::backend
        WS["WebSocket Handler"]:::backend
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        GHA["GitHub Workflows"]:::infra
        Docker["Docker Infrastructure"]:::infra
    end

    %% Connections between Frontend and Backend
    UI -->|"REST_API"| API
    API -->|"handles_kernel"| KernelManager
    KernelManager -->|"configures"| KernelSpec
    API -->|"manages_content"| Content
    API -->|"accesses_config"| Core
    API -->|"handles_sessions"| Session
    Core -->|"supports"| Session
    API -->|"git_operations"| Git

    %% Real-time communication
    UI -->|"WebSockets"| WS

    %% Deployment connections (CI/CD integration)
    API -->|"triggers"| GHA
    API -->|"deploys_via"| Docker

    %% Click Events
    click UI "https://github.com/zasper-io/zasper/tree/main/ui/"
    click API "https://github.com/zasper-io/zasper/blob/main/app.go"
    click Content "https://github.com/zasper-io/zasper/tree/main/content/"
    click KernelManager "https://github.com/zasper-io/zasper/tree/main/kernel/"
    click KernelSpec "https://github.com/zasper-io/zasper/tree/main/kernelspec/"
    click Core "https://github.com/zasper-io/zasper/tree/main/core/"
    click Session "https://github.com/zasper-io/zasper/tree/main/session/"
    click Git "https://github.com/zasper-io/zasper/tree/main/gitclient/"
    click WS "https://github.com/zasper-io/zasper/tree/main/websocket/"
    click GHA "https://github.com/zasper-io/zasper/tree/main/.github/"
    click Docker "https://github.com/zasper-io/zasper/tree/main/docker/"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef backend fill:#f9cb9c,stroke:#b45f06,stroke-width:2px;
    classDef infra fill:#d9ead3,stroke:#38761d,stroke-width:2px;
```
