kat/docs/plan/filestructure.md

# Directory/File Structure

This structure assumes a Go-based project, as hinted by the Go interface definitions in the RFC.

```
kat-system/
├── README.md               # Project overview, build instructions, contribution guide
├── LICENSE                 # Project license (e.g., Apache 2.0, MIT)
├── go.mod                  # Go modules definition
├── go.sum                  # Go modules checksums
├── Makefile                # Build, test, lint, generate code, etc.
│
├── api/
│   └── v1alpha1/
│       ├── kat.proto       # Protocol Buffer definitions for all KAT resources (Workload, Node, etc.)
│       └── generated/      # Generated Go code from .proto files (e.g., using protoc-gen-go)
│                           # Potentially OpenAPI/Swagger specs generated from protos too.
│
├── cmd/
│   ├── kat-agent/
│   │   └── main.go         # Entrypoint for the kat-agent binary
│   └── katcall/
│       └── main.go         # Entrypoint for the katcall CLI binary
│
├── internal/
│   ├── agent/
│   │   ├── agent.go        # Core agent logic, heartbeating, command processing
│   │   ├── runtime.go      # Interface with ContainerRuntime (Podman)
│   │   ├── build.go        # Git-native build process logic
│   │   └── dns_resolver.go # Embedded DNS server logic
│   │
│   ├── leader/
│   │   ├── leader.go       # Core leader logic, reconciliation loops
│   │   ├── schedule.go     # Scheduling algorithm implementation
│   │   ├── ipam.go         # IP Address Management logic
│   │   ├── state_backup.go # etcd backup logic
│   │   └── api_handler.go  # HTTP API request handlers (connects to api/v1alpha1)
│   │
│   ├── api/                # Server-side API implementation details
│   │   ├── server.go       # HTTP server setup, middleware (auth, logging)
│   │   ├── router.go       # API route definitions
│   │   └── auth.go         # Authentication (mTLS, Bearer token) logic
│   │
│   ├── cli/
│   │   ├── commands/       # Subdirectories for each katcall command (apply, get, logs, etc.)
│   │   │   ├── apply.go
│   │   │   └── ...
│   │   ├── client.go       # HTTP client for interacting with KAT API
│   │   └── utils.go        # CLI helper functions
│   │
│   ├── config/
│   │   ├── types.go        # Go structs for Quadlet file kinds if not directly from proto
│   │   ├── parse.go        # Logic for parsing and validating *.kat files (Quadlets, cluster.kat)
│   │   └── defaults.go     # Default values for configurations
│   │
│   ├── store/
│   │   ├── interface.go    # Definition of StateStore interface (as in RFC 5.1)
│   │   └── etcd.go         # etcd implementation of StateStore, embedded etcd setup
│   │
│   ├── runtime/
│   │   ├── interface.go    # Definition of ContainerRuntime interface (as in RFC 6.1)
│   │   └── podman.go       # Podman implementation of ContainerRuntime
│   │
│   ├── network/
│   │   ├── wireguard.go    # WireGuard setup and peer management logic
│   │   └── types.go        # Network related internal types
│   │
│   ├── pki/
│   │   ├── ca.go           # Certificate Authority management (generation, signing)
│   │   └── certs.go        # Certificate generation and handling utilities
│   │
│   ├── observability/
│   │   ├── logging.go      # Logging setup for components
│   │   ├── metrics.go      # Metrics collection and exposure logic
│   │   └── events.go       # Event recording and retrieval logic
│   │
│   ├── types/              # Core internal data structures if not covered by API protos
│   │   ├── node.go
│   │   ├── workload.go
│   │   └── ...
│   │
│   ├── constants/
│   │   └── constants.go    # Global constants (etcd key prefixes, default ports, etc.)
│   │
│   └── utils/
│       ├── utils.go        # Common utility functions (error handling, string manipulation)
│       └── tar.go          # Utilities for handling tar.gz Quadlet archives
│
├── docs/
│   ├── rfc/
│   │   └── RFC001-KAT.md   # The source RFC document
│   ├── user-guide/         # User documentation (installation, getting started, tutorials)
│   │   ├── installation.md
│   │   └── basic_usage.md
│   └── api-guide/          # API usage documentation (perhaps generated)
│
├── examples/
│   ├── simple-service/     # Example Quadlet for a simple service
│   │   ├── workload.kat
│   │   └── VirtualLoadBalancer.kat
│   ├── git-build-service/  # Example Quadlet for a service built from Git
│   │   ├── workload.kat
│   │   └── build.kat
│   ├── job/                # Example Quadlet for a Job
│   │   ├── workload.kat
│   │   └── job.kat
│   └── cluster.kat         # Example cluster configuration file
│
├── scripts/
│   ├── setup-dev-env.sh    # Script to set up development environment
│   ├── lint.sh             # Code linting script
│   ├── test.sh             # Script to run all tests
│   └── gen-proto.sh        # Script to generate Go code from .proto files
│
└── test/
    ├── unit/               # Unit tests (mirroring internal/ structure)
    ├── integration/        # Integration tests (e.g., agent-leader interaction)
    └── e2e/                # End-to-end tests (testing full cluster operations via katcall)
        ├── fixtures/       # Test Quadlet files
        └── e2e_test.go
```

**Description of Key Files/Directories and Relationships:**

*   **`api/v1alpha1/kat.proto`**: The source of truth for all resource definitions. `make generate` (or `scripts/gen-proto.sh`) would convert this into Go structs in `api/v1alpha1/generated/`. These structs will be used across the `internal/` packages.
*   **`cmd/kat-agent/main.go`**: Initializes and runs the `kat-agent`. It will instantiate components from `internal/store` (for etcd), `internal/agent`, `internal/leader`, `internal/pki`, `internal/network`, and `internal/api` (for the API server if elected leader).
*   **`cmd/katcall/main.go`**: Entry point for the CLI. It uses `internal/cli` components to parse commands and interact with the KAT API via `internal/cli/client.go`.
*   **`internal/config/parse.go`**: Used by the Leader to parse submitted Quadlet `tar.gz` archives and by `kat-agent init` to parse `cluster.kat`.
*   **`internal/store/etcd.go`**: Implements `StateStore` and manages the embedded etcd instance. Used by both Agent (for watching) and Leader (for all state modifications, leader election).
*   **`internal/runtime/podman.go`**: Implements `ContainerRuntime`. Used by `internal/agent/runtime.go` to manage containers based on Podman.
*   **`internal/agent/agent.go`** and **`internal/leader/leader.go`**: Contain the core state machines and logic for the respective roles. The `kat-agent` binary decides which role's logic to activate based on leader election status.
*   **`internal/pki/ca.go`**: Used by `kat-agent init` to create the CA, and by the Leader to sign CSRs from joining agents.
*   **`internal/network/wireguard.go`**: Used by agents to configure their local WireGuard interface based on data synced from etcd (managed by the Leader).
*   **`internal/leader/api_handler.go`**: Implements the HTTP handlers for the API, using other leader components (scheduler, IPAM, store) to fulfill requests.