# olyxz16/sherpa architecture

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

## Overview

##### Project type and purpose
- This is a full-stack web application written in Go (backend) and Vue/Vite (frontend).
- The backend exposes HTTP endpoints (with healthcheck and server binaries) for user authentication, file management, and GitHub-based OAuth. It persists data to a SQL database and performs file encryption.
- The frontend is a single-page application (SPA) in Vue that lets users log in (including via GitHub), upload/download/encrypt files, and manage their account.

##### File structure
- Top level:
- cmd/server and cmd/healthcheck: two Go binaries (main API server and a simple healthcheck server).
- config, crypto, domain, infrastructure, interfaces: layers of a Go “clean-architecture” or hexagonal style.
- Dockerfile(s), docker-compose*.yml, Makefile: containerization, local/dev setups.
- views/: the entire Vue/Vite frontend application, including components, routing, stores, static assets.
- Layers:
- domain/model & domain/repository: business entities (User, Auth, File) and domain-level repository interfaces.
- infrastructure/persistence & infrastructure/jwt: concrete implementations (SQL via sqlc, migrations; JWT cookie handling).
- interfaces/handlers & interfaces/http & interfaces/middleware: HTTP transport, route definitions, handler wiring, auth middleware.
- crypto: file encryption and master key management.
- Configuration: config/*.go for central config and logger setup; sqlc.yaml for code generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    User["User Browser"]:::external
    Frontend["Frontend SPA (Vue/Vite)"]:::presentation
    User -->|"Interacts via HTTP/HTTPS"| Frontend
    click Frontend "https://github.com/olyxz16/sherpa/tree/master/views/"

    %% Backend Server Binaries
    subgraph "Backend API Server"
        direction TB
        ServerBinary["API Server\n(cmd/server/main.go)"]:::infra
        HealthBinary["Healthcheck Server\n(cmd/healthcheck/main.go)"]:::infra
        click ServerBinary "https://github.com/olyxz16/sherpa/blob/master/cmd/server/main.go"
        click HealthBinary "https://github.com/olyxz16/sherpa/blob/master/cmd/healthcheck/main.go"

        %% HTTP Layer
        subgraph "HTTP Layer"
            direction TB
            HTTPServer["server.go"]:::infra
            Routes["routes.go"]:::infra
            click HTTPServer "https://github.com/olyxz16/sherpa/blob/master/interfaces/http/server.go"
            click Routes "https://github.com/olyxz16/sherpa/blob/master/interfaces/http/routes.go"
        end

        %% Middleware
        subgraph "Middleware"
            direction TB
            AuthMiddleware["JWT Auth Middleware\n(auth.go)"]:::infra
            click AuthMiddleware "https://github.com/olyxz16/sherpa/blob/master/interfaces/middleware/auth.go"
        end

        %% Handlers
        subgraph "Handlers"
            direction TB
            UserHandler["User Handler\n(user.go)"]:::infra
            FileHandler["File Handler\n(file.go)"]:::infra
            GHAuthHandler["GitHub OAuth Handler\n(auth.go)"]:::infra
            GHUserHandler["GitHub User Handler\n(user.go)"]:::infra
            HealthHandler["Healthcheck Handler\n(health.go)"]:::infra

            click UserHandler "https://github.com/olyxz16/sherpa/blob/master/interfaces/handlers/user/user.go"
            click FileHandler "https://github.com/olyxz16/sherpa/blob/master/interfaces/handlers/user/file.go"
            click GHAuthHandler "https://github.com/olyxz16/sherpa/blob/master/interfaces/handlers/github/auth.go"
            click GHUserHandler "https://github.com/olyxz16/sherpa/blob/master/interfaces/handlers/github/user.go"
            click HealthHandler "https://github.com/olyxz16/sherpa/blob/master/interfaces/handlers/health.go"
        end

        %% Domain Layer
        subgraph "Domain"
            direction TB
            subgraph "Models"
                AuthModel["auth.go"]:::domain
                FileModel["file.go"]:::domain
                UserModel["user.go"]:::domain
                click AuthModel "https://github.com/olyxz16/sherpa/blob/master/domain/model/auth.go"
                click FileModel "https://github.com/olyxz16/sherpa/blob/master/domain/model/file.go"
                click UserModel "https://github.com/olyxz16/sherpa/blob/master/domain/model/user.go"
            end
            subgraph "Repository Interfaces"
                AuthRepoIntf["auth.go"]:::domain
                FileRepoIntf["file.go"]:::domain
                UserRepoIntf["user.go"]:::domain
                click AuthRepoIntf "https://github.com/olyxz16/sherpa/blob/master/domain/repository/auth.go"
                click FileRepoIntf "https://github.com/olyxz16/sherpa/blob/master/domain/repository/file.go"
                click UserRepoIntf "https://github.com/olyxz16/sherpa/blob/master/domain/repository/user.go"
            end
        end

        %% Infrastructure & Persistence
        subgraph "Infrastructure"
            direction TB
            subgraph "Persistence"
                DBSetup["db.go"]:::infra
                Migrations["migrations/"]:::infra
                SQLAuth["auth.sql"]:::infra
                SQLFile["file.sql"]:::infra
                SQLUser["user.sql"]:::infra
                RepoImplAuth["auth.go"]:::infra
                RepoImplFile["file.go"]:::infra
                RepoImplUser["user.go"]:::infra
                SQLC["sqlc/"]:::infra

                click DBSetup "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/db.go"
                click Migrations "https://github.com/olyxz16/sherpa/tree/master/infrastructure/persistence/migrations/"
                click SQLAuth "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/query/auth.sql"
                click SQLFile "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/query/file.sql"
                click SQLUser "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/query/user.sql"
                click RepoImplAuth "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/repository/auth.go"
                click RepoImplFile "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/repository/file.go"
                click RepoImplUser "https://github.com/olyxz16/sherpa/blob/master/infrastructure/persistence/repository/user.go"
                click SQLC "https://github.com/olyxz16/sherpa/tree/master/infrastructure/persistence/sqlc/"
            end

            JWTInfra["JWT Cookie Handling\n(cookies.go)"]:::infra
            click JWTInfra "https://github.com/olyxz16/sherpa/blob/master/infrastructure/jwt/cookies.go"
        end

        %% Crypto Module
        subgraph "Crypto Module"
            direction TB
            CryptoFile["fileencryption.go"]:::infra
            CryptoMaster["masterkey.go"]:::infra
            click CryptoFile "https://github.com/olyxz16/sherpa/blob/master/crypto/fileencryption.go"
            click CryptoMaster "https://github.com/olyxz16/sherpa/blob/master/crypto/masterkey.go"
        end

        %% Config & Logging
        subgraph "Configuration"
            direction TB
            ConfigFile["config.go"]:::infra
            LoggerFile["logger.go"]:::infra
            click ConfigFile "https://github.com/olyxz16/sherpa/blob/master/config/config.go"
            click LoggerFile "https://github.com/olyxz16/sherpa/blob/master/config/logger.go"
        end

    end

    %% External Services
    GitHub["GitHub OAuth"]:::external
    Postgres["PostgreSQL DB"]:::infra

    %% DevOps
    subgraph "DevOps & CI/CD"
        direction TB
        Dockerfiles["Dockerfile(s)"]:::infra
        Compose["docker-compose*.yml"]:::infra
        CI["CI Pipeline\n(ci.yml)"]:::infra
        click Dockerfiles "https://github.com/olyxz16/sherpa/tree/master/Dockerfile"
        click Dockerfiles "https://github.com/olyxz16/sherpa/blob/master/Dockerfile.migrate"
        click Compose "https://github.com/olyxz16/sherpa/blob/master/docker-compose.yml"
        click Compose "https://github.com/olyxz16/sherpa/blob/master/docker-compose.dev.yml"
        click Compose "https://github.com/olyxz16/sherpa/blob/master/docker-compose.local.yml"
        click CI "https://github.com/olyxz16/sherpa/blob/master/.github/workflows/ci.yml"
    end

    %% Data Flows
    Frontend -->|HTTPS JSON| ServerBinary
    ServerBinary --> HTTPServer
    HTTPServer --> Routes
    Routes --> AuthMiddleware
    AuthMiddleware --> UserHandler
    AuthMiddleware --> FileHandler
    Routes --> HealthHandler
    Routes --> GHAuthHandler
    GHAuthHandler --> GHUserHandler
    UserHandler -->|"Invokes"| AuthModel
    FileHandler -->|"Invokes"| FileModel
    UserHandler -->|"Invokes"| UserModel
    UserHandler --> JWTInfra
    GHAuthHandler -->|OAuth Redirect/API| GitHub
    FileHandler -->CryptoFile
    FileHandler -->CryptoMaster
    UserHandler -->AuthRepoIntf
    FileHandler -->FileRepoIntf
    UserHandler -->UserRepoIntf
    AuthRepoIntf --> RepoImplAuth
    FileRepoIntf --> RepoImplFile
    UserRepoIntf --> RepoImplUser
    RepoImplAuth --> SQLAuth
    RepoImplFile --> SQLFile
    RepoImplUser --> SQLUser
    RepoImplAuth --> SQLC
    RepoImplFile --> SQLC
    RepoImplUser --> SQLC
    DBSetup --> Postgres
    Migrations --> Postgres
    ServerBinary --> ConfigFile
    ServerBinary --> LoggerFile
    ServerBinary --> Dockerfiles
    ServerBinary --> Compose
    ServerBinary --> CI

    %% Database connections
    RepoImplAuth -->|SQL| Postgres
    RepoImplFile -->|SQL| Postgres
    RepoImplUser -->|SQL| Postgres

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef domain fill:#A9DFBF,stroke:#145A32,color:#1B2631
    classDef infra fill:#FAD7A0,stroke:#B9770E,color:#1B2631
    classDef external fill:#D6EAF8,stroke:#2874A6,color:#1B2631
```
