# 0siriz/keyweaver architecture

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

- Interactive diagram: https://gitdiagram.com/0siriz/keyweaver
- Repository: https://github.com/0siriz/keyweaver

## Overview

##### Project Type and Purpose
- This is an open-source command-line tool (KeyWeaver) written in Go.
- Purpose: to automate the setup and management of a Public Key Infrastructure (PKI), supporting from single to three-tiered Certification Authorities (CAs).

##### File Structure
- Top-level files: Makefile, ca.yaml (configuration template), README.md, go.mod, go.sum.
- cmd/keyweaver-cli: CLI entrypoint, root and subcommands under cmd/ca.
- pkg/: core libraries
- pkg/models: data structures (e.g. CA, certificate specs)
- pkg/cert: certificate generation logic
- pkg/storage: persistence layer (e.g. writing keys and certs to disk)
- No frontend or service layers—purely a CLI tool with pluggable back-ends.

##### README
- Confirms focus on PKI tooling and multi-tier CA generation.

a. Main Components
- CLI Runner (cmd/keyweaver-cli/main.go & root.go)
- Command Handlers (cmd/keyweaver-cli/cmd/ca/*.go)
- Configuration Loader (reads ca.yaml)
- Core Logic
– Models (pkg/models)
– Certificate Engine (pkg/cert)
– Storage Engine (pkg/storage)
- External I/O: file system (for keys, certs), optional HSM or KMS integration points.

b. Relationships and Interactions
1. User invokes CLI with subcommand (e.g. “keyweaver-cli ca init”).
2. Root command loads global flags, parses commands.
3. CA subcommand loads YAML config into pkg/models.
4. pkg/models passes structured input to pkg/cert to generate keys and certificates.
5. pkg/storage persists generated artifacts to disk (PEM files, directories).
6. CLI reports status/error back to user.

c. Architectural Patterns and Principles
- Separation of Concerns: CLI parsing vs. business logic vs. persistence.
- Pluggable modules: storage interface can be extended to support databases, cloud KMS, etc.
- Single Responsibility per package: models only define data, cert handles crypto, storage handles I/O.

d. Key Technologies
- Go’s standard library (crypto/x509, encoding/pem, file I/O).
- Cobra (or similar) for CLI parsing (inferred).
- YAML parsing (via ca.yaml) for flexible CA definitions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    User[/"User/Terminal"/]:::external
    CLI["CLI Runner"]:::cli
    Handlers["CA Command Handlers"]:::cli
    Config["Configuration Loader"]:::logic
    Models["Models (pkg/models)"]:::logic
    Cert["Certificate Engine"]:::logic
    Storage["Storage Engine"]:::persistence
    FS["File System"]:::external
    HSM["HSM / KMS (optional)"]:::external

    subgraph "Project Resources"
        GoMod["go.mod / go.sum"]:::doc
        Makefile["Makefile"]:::doc
        README["README.md"]:::doc
    end

    %% Flow
    User -->|"invokes CLI"| CLI
    CLI -->|"parsed flags"| Handlers
    Handlers -->|"loads config"| Config
    Config -->|"CA spec struct"| Models
    Models -->|"CA spec"| Cert
    Cert -->|"X.509 cert"| Storage
    Storage -->|"PEM files"| FS
    Storage -->|"optional integration"| HSM

    %% Click Events
    click CLI "https://github.com/0siriz/keyweaver/blob/main/cmd/keyweaver-cli/main.go"
    click CLI "https://github.com/0siriz/keyweaver/blob/main/cmd/keyweaver-cli/cmd/root.go"
    click Handlers "https://github.com/0siriz/keyweaver/blob/main/cmd/keyweaver-cli/cmd/ca/ca.go"
    click Handlers "https://github.com/0siriz/keyweaver/blob/main/cmd/keyweaver-cli/cmd/ca/init.go"
    click Config "https://github.com/0siriz/keyweaver/blob/main/ca.yaml"
    click Config "https://github.com/0siriz/keyweaver/blob/main/pkg/models/models.go"
    click Models "https://github.com/0siriz/keyweaver/blob/main/pkg/models/models.go"
    click Cert "https://github.com/0siriz/keyweaver/blob/main/pkg/cert/cert.go"
    click Storage "https://github.com/0siriz/keyweaver/blob/main/pkg/storage/storage.go"
    click GoMod "https://github.com/0siriz/keyweaver/blob/main/go.mod"
    click GoMod "https://github.com/0siriz/keyweaver/blob/main/go.sum"
    click Makefile "https://github.com/0siriz/keyweaver/tree/main/Makefile"
    click README "https://github.com/0siriz/keyweaver/blob/main/README.md"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#3B82F6,stroke-width:2px
    classDef logic fill:#D4F5D4,stroke:#22C55E,stroke-width:2px
    classDef persistence fill:#FFE4C4,stroke:#F59E0B,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#9CA3AF,stroke-width:2px,stroke-dasharray: 5 5
    classDef doc fill:#FFF1D6,stroke:#D97706,stroke-width:2px,stroke-dasharray: 3 3
```
