# mscno/esec architecture

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

- Interactive diagram: https://gitdiagram.com/mscno/esec
- Repository: https://github.com/mscno/esec

## Overview

##### Project Type and Purpose
- This is a Go-based **full-stack** project combining:
- A **CLI tool/library** (`cmd/esec`, `pkg/...`) for local encryption/decryption and “run” workflows.
- An **API server** (`cmd/esec-server`, `server/...`) exposing gRPC/Connect endpoints for remote secret management (“cloud” commands).
- A **shared Go library** (`pkg/*`) providing core crypto, file-format parsing, client utilities, and keyring handling.

##### File Structure Analysis
- Top-level executables:
- `cmd/esec` – CLI entrypoint with subcommands under `commands/`.
- `cmd/esec-server` – HTTP/Connect server that implements the backend.
- Shared library code (`pkg/*`):
- `pkg/crypto` – encryption/decryption routines.
- `pkg/fileutils`, `pkg/format`, `pkg/json`, `pkg/keyring` – file parsing and format handling.
- `pkg/auth`, `pkg/client` – GitHub auth and gRPC client.
- Server side (`server/`):
- `server/proto` & `gen/proto` – .proto definitions and generated Go code.
- `server/connect_server.go` & `server/server.go` – setup of gRPC/Connect handlers.
- `server/middleware` – auth, CORS, logging, rate limiting.
- `server/stores` – implementations of data stores (BoltDB, memory) for users, organizations, projects.
- Configuration & Deployment:
- GitHub workflows, GoReleaser for CLI and server releases.
- `.esec-keyring`, environment variables for key lookup.

##### Essential Elements
- Clearly separate local-only (encrypt/decrypt) vs remote (cloud) functionality.
- Middleware layers in server pipeline.
- Lookup hierarchy (env vars → keyring file).
- File-format modules (`.ejson`, `.env`) and their parser/encryptor.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User / Developer"]:::external

    %% CLI Application
    subgraph "CLI Application" 
        direction TB
        CLI_main["Entry: cmd/esec/main.go"]:::cli
        CLI_commands["Subcommands: cmd/esec/commands/"]:::cli
        CLI_version["Version Cmd: cmd/esec/version.go"]:::cli
        CLI_main --> CLI_commands
        CLI_main --> CLI_version
    end

    %% Key Lookup and Local FS
    subgraph "Local Environment" 
        direction TB
        EnvVars["Env Vars"]:::storage
        KeyringFile[".esec-keyring"]:::storage
        LocalFS["Local File System"]:::storage
    end

    %% Shared Library
    subgraph "Shared Library (pkg/*)" 
        direction TB
        Crypto["pkg/crypto"]:::shared
        FileUtils["pkg/fileutils"]:::shared
        Format["pkg/format"]:::shared
        JSON["pkg/json"]:::shared
        Keyring["pkg/keyring"]:::shared
        AuthLib["pkg/auth"]:::shared
        ClientLib["pkg/client"]:::shared
        Dotenv["pkg/dotenv"]:::shared
        OSKeyring["pkg/oskeyring"]:::shared
        ProjectFile["pkg/projectfile"]:::shared
    end

    %% API Server
    subgraph "API Server" 
        direction TB
        Server_main["Entry: cmd/esec-server/main.go"]:::server
        Server_setup["gRPC/Connect Handlers"]:::server
        subgraph "Middleware Layer"
            direction TB
            MW_auth["auth"]:::server
            MW_cors["cors"]:::server
            MW_logger["logger"]:::server
            MW_rate["rate_limit"]:::server
            MW_recover["recovery"]:::server
        end
        subgraph "Service Handlers"
            direction TB
            Svc_org["Organizations"]:::server
            Svc_proj["Projects"]:::server
            Svc_keys["Keys"]:::server
            Svc_shares["Shares"]:::server
            Svc_sync["Sync"]:::server
        end
        subgraph "Data Stores"
            direction TB
            Store_Bolt["BoltDB Adapter"]:::storage
            Store_Mem["In-Memory Adapter"]:::storage
        end
        subgraph "Data Models"
            direction TB
            Model_org["organization.go"]:::server
            Model_proj["project.go"]:::server
            Model_user["user.go"]:::server
        end
        ProtoDef["Proto Definitions"]:::server
        GenCode1["Generated: esec.pb.go"]:::server
        GenCode2["Generated: esec.connect.go"]:::server

        Server_main --> Server_setup
        Server_setup --> MW_auth
        Server_setup --> MW_cors
        Server_setup --> MW_logger
        Server_setup --> MW_rate
        Server_setup --> MW_recover
        MW_recover --> Svc_org
        MW_recover --> Svc_proj
        MW_recover --> Svc_keys
        MW_recover --> Svc_shares
        MW_recover --> Svc_sync
        Svc_org --> Store_Bolt
        Svc_org --> Store_Mem
        Svc_proj --> Store_Bolt
        Svc_proj --> Store_Mem
        Svc_keys --> Store_Bolt
        Svc_shares --> Store_Bolt
        Svc_sync --> Store_Bolt
        Svc_org --> Model_org
        Svc_proj --> Model_proj
        Svc_keys --> Model_user
        Server_setup --> ProtoDef
        ProtoDef --> GenCode1
        ProtoDef --> GenCode2
    end

    %% External
    GitHub["GitHub OAuth"]:::external

    %% Flows
    User --> CLI_main
    CLI_main --> EnvVars
    CLI_main --> KeyringFile
    CLI_main --> Crypto
    CLI_main --> ClientLib
    CLI_main --> LocalFS
    LocalFS --> FileUtils
    FileUtils --> Format
    Format --> Crypto
    Crypto --> LocalFS
    CLI_main --> Dotenv
    CLI_main --> OSKeyring
    CLI_main --> ProjectFile

    CLI_main -->|Cloud Commands| ClientLib
    ClientLib --> Server_main
    Server_main --> Server_setup

    ClientLib -->|"HTTP/2 gRPC/Connect"| Server_setup

    Server_setup -->|"Response"| ClientLib
    ClientLib --> CLI_main

    CLI_main -->|GitHub Auth Proxy| AuthLib
    AuthLib --> GitHub
    Server_setup --> AuthLib
    AuthLib --> GitHub

    %% Click Events
    click CLI_main "https://github.com/mscno/esec/blob/master/cmd/esec/main.go"
    click CLI_commands "https://github.com/mscno/esec/tree/master/cmd/esec/commands/"
    click CLI_version "https://github.com/mscno/esec/blob/master/cmd/esec/version.go"
    click Server_main "https://github.com/mscno/esec/blob/master/cmd/esec-server/main.go"
    click Server_setup "https://github.com/mscno/esec/blob/master/server/connect_server.go"
    click Server_setup "https://github.com/mscno/esec/blob/master/server/server.go"
    click MW_auth "https://github.com/mscno/esec/blob/master/server/middleware/auth.go"
    click MW_cors "https://github.com/mscno/esec/blob/master/server/middleware/cors.go"
    click MW_logger "https://github.com/mscno/esec/blob/master/server/middleware/logger.go"
    click MW_rate "https://github.com/mscno/esec/blob/master/server/middleware/rate_limit.go"
    click MW_recover "https://github.com/mscno/esec/blob/master/server/middleware/recovery.go"
    click Store_Bolt "https://github.com/mscno/esec/tree/master/server/stores/"
    click Model_org "https://github.com/mscno/esec/blob/master/server/model/organization.go"
    click Model_proj "https://github.com/mscno/esec/blob/master/server/model/project.go"
    click Model_user "https://github.com/mscno/esec/blob/master/server/model/user.go"
    click ProtoDef "https://github.com/mscno/esec/blob/master/server/proto/esec/esec.proto"
    click GenCode1 "https://github.com/mscno/esec/blob/master/gen/proto/go/esec/esec.pb.go"
    click GenCode2 "https://github.com/mscno/esec/blob/master/gen/proto/go/esecpbconnect/esec.connect.go"
    click Crypto "https://github.com/mscno/esec/blob/master/pkg/crypto/crypto.go"
    click FileUtils "https://github.com/mscno/esec/blob/master/pkg/fileutils/fileformats.go"
    click Format "https://github.com/mscno/esec/blob/master/pkg/format/format.go"
    click JSON "https://github.com/mscno/esec/blob/master/pkg/json/format.go"
    click Keyring "https://github.com/mscno/esec/blob/master/pkg/keyring/keyring_format.go"
    click AuthLib "https://github.com/mscno/esec/blob/master/pkg/auth/auth.go"
    click ClientLib "https://github.com/mscno/esec/blob/master/pkg/client/client.go"
    click Dotenv "https://github.com/mscno/esec/blob/master/pkg/dotenv/dotenv.go"
    click OSKeyring "https://github.com/mscno/esec/blob/master/pkg/oskeyring/service.go"
    click ProjectFile "https://github.com/mscno/esec/blob/master/pkg/projectfile/project.go"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef server fill:#DFF2D8,stroke:#22863A,color:#22863A
    classDef shared fill:#F1F8FF,stroke:#0366d6,color:#0366d6
    classDef storage fill:#F6F8FA,stroke:#6A737D,color:#6A737D
    classDef external fill:#FFF5B1,stroke:#D29922,color:#D29922
```
