cozystack/docs/agents/overview.md

Cozystack Project Overview

This document provides detailed information about Cozystack project structure and conventions for AI agents.

About Cozystack

Cozystack is an open-source Kubernetes-based platform and framework for building cloud infrastructure. It provides:

• Managed Services: Databases, VMs, Kubernetes clusters, object storage, and more
• Multi-tenancy: Full isolation and self-service for tenants
• GitOps-driven: FluxCD-based continuous delivery
• Modular Architecture: Extensible with custom packages and services
• Developer Experience: Simplified local development with cozypkg tool

The platform exposes infrastructure services via the Kubernetes API with ready-made configs, built-in monitoring, and alerts.

Code Layout

.
├── packages/               # Main directory for cozystack packages
│   ├── core/              # Core platform logic charts (installer, platform)
│   ├── system/            # System charts (CSI, CNI, operators, etc.)
│   ├── apps/              # User-facing charts shown in dashboard catalog
│   └── extra/             # Tenant-specific modules, singleton charts which are used as dependencies
├── dashboards/            # Grafana dashboards for monitoring
├── hack/                  # Helper scripts for local development
│   └── e2e-apps/         # End-to-end application tests
├── scripts/               # Scripts used by cozystack container
│   └── migrations/       # Version migration scripts
├── docs/                  # Documentation
│   ├── agents/           # AI agent instructions
│   └── changelogs/       # Release changelogs
├── cmd/                   # Go command entry points
│   ├── cozystack-api/
│   ├── cozystack-controller/
│   └── cozystack-assets-server/
├── internal/              # Internal Go packages
│   ├── controller/       # Controller implementations
│   └── lineagecontrollerwebhook/
├── pkg/                   # Public Go packages
│   ├── apis/
│   ├── apiserver/
│   └── registry/
└── api/                   # Kubernetes API definitions (CRDs)
    └── v1alpha1/

Package Structure

Every package is a Helm chart following the umbrella chart pattern:

packages/<category>/<package-name>/
├── Chart.yaml                           # Chart definition and parameter docs
├── Makefile                             # Development workflow targets
├── charts/                              # Vendored upstream charts
├── images/                              # Dockerfiles and image build context
├── patches/                             # Optional upstream chart patches
├── templates/                           # Additional manifests
├── templates/dashboard-resourcemap.yaml # Dashboard resource mapping
├── values.yaml                          # Override values for upstream
└── values.schema.json                   # JSON schema for validation and UI

Conventions

Helm Charts

• Follow umbrella chart pattern for system components
• Include upstream charts in charts/ directory (vendored, not referenced)
• Override configuration in root values.yaml
• Use values.schema.json for input validation and dashboard UI rendering

Go Code

• Follow standard Go conventions and idioms
• Use controller-runtime patterns for Kubernetes controllers
• Prefer kubebuilder for API definitions and controllers
• Add proper error handling and structured logging

Git Commits

• Use format: [component] Description
• Always use --signoff flag
• Reference PR numbers when available
• Keep commits atomic and focused
• Follow conventional commit format for changelogs

Documentation

Documentation is organized as follows:

• docs/ - General documentation
• docs/agents/ - Instructions for AI agents
• docs/changelogs/ - Release changelogs
• Main website: https://github.com/cozystack/website

Things Agents Should Not Do

Never Edit These

• Do not modify files in /vendor/ (Go dependencies)
• Do not edit generated files: zz_generated.*.go
• Do not change go.mod/go.sum manually (use go get)
• Do not edit upstream charts in packages/*/charts/ directly (use patches)
• Do not modify image digests in values.yaml (generated by build)

Version Control

• Do not commit built artifacts from _out
• Do not commit test artifacts or temporary files

Git Operations

• Do not force push to main/master
• Do not update git config
• Do not perform destructive operations without explicit request

Core Components

• Do not modify packages/core/platform/ without understanding migration impact