# saltbo/zpan architecture

> Architecture diagram of the GitHub repository saltbo/zpan, 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/saltbo/zpan
- Repository: https://github.com/saltbo/zpan

## Overview

##### Main Components
- Frontend/UI: Represented by the “web” directory, which holds the static assets (HTML, CSS, JS) built into a web application (likely a single-page app). It’s the user’s primary interaction point.
- API / Backend Server:
- The “cmd” directory (e.g., cmd/server.go) and “main.go” define the application’s entry points.
- The “internal/app” folder holds the business logic, with subdirectories like “api”, “dao”, “service”, “usecase”, “repo” – suggesting a layered architecture (controller → service → repository → persistence).
- Data Layer: Even if there is no explicit “database” folder, your “dao” and “repo” packages indicate that database interactions are abstracted through these layers. You might have a relational database behind these layers.
- External Services & Providers:
- The “internal/pkg/provider” package and the “pkg/nos”, “pkg/obs” directories indicate integrations with external cloud storage providers (S3, OSS, OBS, etc.).
- They act as connectors between your business logic and third-party storage services.
- Infrastructure & Deployment: Files like Dockerfile, heroku.yml, Procfile, and “deployments/” indicate containerized deployment and integrations with cloud tooling, while GitHub workflows encapsulate CI/CD processes.

##### Relationships and Interactions between Components
- The Frontend (Web UI) issues HTTP requests to the API server.
- The API server (in “internal/app/api” and “cmd”) handles incoming requests, performs authentication (note the “internal/pkg/middleware/auth.go” and “authz” usecase), and routes requests.
- The service and usecase layers in “internal/app/service” and “internal/app/usecase” contain the core business logic that processes file management, sharing, storage operations, and user management.
- Data persistence is managed by DAO (data access object) and repository layers (“internal/app/dao”, “internal/app/repo”), interfacing with the underlying database.
- Cloud storage integrations (in packages within “internal/pkg/provider” and “pkg/nos”, “pkg/obs”) process the actual storage functions by interacting with external cloud storage endpoints.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separate concerns by dividing responsibilities among the API layer, service/usecase layer, repository layer, and external integrations.
- Modular Design: Encapsulation is evident in the separation of different functionalities (e.g., API, DAO, entity definitions, business logic, and external providers).
- Dependency Injection: Files like “internal/app/wire.go” and “internal/app/wire_gen.go” indicate automated wiring of dependencies.
- Extensibility: The project supports multiple cloud storage providers via distinct packages, signaling an extensible plugin-like approach.

##### Relevant Technologies and Frameworks
- Written in Go – leveraging native Go modules (go.mod, go.sum) for dependency management.
- Containerization with Docker (Dockerfile, .dockerignore) and deployment scripts (heroku.yml, Procfile).
- CI/CD workflows managed through GitHub Actions (see .github/workflows).
- Frontend assets appear pre-built (likely using a modern JavaScript framework) and served as static assets from the “web/dist” folder.
- Integration with cloud storage providers via S3 and others (through packages under pkg and internal/pkg/provider).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        WebClient["Web Client"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server Layer"
        APIServer["API Gateway/Server"]:::api
        APILayer["API Controllers & Routes"]:::api
        AuthMiddleware["Authentication Middleware"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BusinessLogic["Business Logic & Service Layer"]:::logic
        DependencyInjection["Dependency Injection Setup"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        DataAccess["Data Access (DAO & Repo)"]:::data
        Database[(Database)]:::database
    end

    %% External Integrations
    subgraph "External Cloud Integrations"
        CloudStorage["Cloud Storage Integrations"]:::storage
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        DeploymentInfra["Deployment & Infrastructure"]:::infra
    end

    %% Connections
    WebClient -->|"HTTP request"| APIServer
    APIServer -->|"routes"| APILayer
    APILayer -->|"calls"| BusinessLogic
    BusinessLogic -->|"persists data"| DataAccess
    DataAccess -->|"queries"| Database
    BusinessLogic -->|"storage operations"| CloudStorage

    %% Additional connections
    APIServer -->|"auth via"| AuthMiddleware
    DependencyInjection -.-> APIServer
    DependencyInjection -.-> BusinessLogic
    DeploymentInfra ---|"deploys"| WebClient
    DeploymentInfra ---|"deploys"| APIServer

    %% Click Events for Frontend/UI
    click WebClient "https://github.com/saltbo/zpan/tree/master/web/dist"
    click WebClient "https://github.com/saltbo/zpan/blob/master/web/web.go"
    click WebClient "https://github.com/saltbo/zpan/blob/master/web/efs.go"

    %% Click Events for API/Backend Entry Points
    click APIServer "https://github.com/saltbo/zpan/blob/master/cmd/server.go"
    click APIServer "https://github.com/saltbo/zpan/blob/master/cmd/root.go"
    click APIServer "https://github.com/saltbo/zpan/blob/master/main.go"

    %% Click Event for API Layer
    click APILayer "https://github.com/saltbo/zpan/blob/master/internal/app/api/router.go"

    %% Click Events for Business Logic & Service Layer
    click BusinessLogic "https://github.com/saltbo/zpan/tree/master/internal/app/service"
    click BusinessLogic "https://github.com/saltbo/zpan/tree/master/internal/app/usecase"

    %% Click Events for Data Access Layer
    click DataAccess "https://github.com/saltbo/zpan/tree/master/internal/app/dao"
    click DataAccess "https://github.com/saltbo/zpan/tree/master/internal/app/repo"
    click DataAccess "https://github.com/saltbo/zpan/tree/master/internal/app/model"

    %% Click Events for External Cloud Storage Integrations
    click CloudStorage "https://github.com/saltbo/zpan/tree/master/internal/pkg/provider"
    click CloudStorage "https://github.com/saltbo/zpan/tree/master/pkg/nos"
    click CloudStorage "https://github.com/saltbo/zpan/tree/master/pkg/obs"

    %% Click Event for Authentication Middleware
    click AuthMiddleware "https://github.com/saltbo/zpan/blob/master/internal/pkg/middleware/auth.go"

    %% Click Events for Dependency Injection Setup
    click DependencyInjection "https://github.com/saltbo/zpan/blob/master/internal/app/wire.go"
    click DependencyInjection "https://github.com/saltbo/zpan/blob/master/internal/app/wire_gen.go"

    %% Click Events for Deployment & Infrastructure
    click DeploymentInfra "https://github.com/saltbo/zpan/tree/master/Dockerfile"
    click DeploymentInfra "https://github.com/saltbo/zpan/blob/master/heroku.yml"
    click DeploymentInfra "https://github.com/saltbo/zpan/tree/master/Procfile"
    click DeploymentInfra "https://github.com/saltbo/zpan/blob/master/deployments/zpan.service"
    click DeploymentInfra "https://github.com/saltbo/zpan/tree/master/.github/workflows"

    %% Style Definitions
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef logic fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef data fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef storage fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef infra fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef database fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
```
