docs: map existing codebase
This commit is contained in:
Viktor Barzin
parent
275eb5aec8
commit
c8e9c41afc
8 changed files with 1475 additions and 1 deletions
192
.planning/codebase/CONVENTIONS.md
Normal file
192
.planning/codebase/CONVENTIONS.md
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** 2026-02-23
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
**Terraform Files:**
|
||||
- `main.tf` - Primary resource definitions and module calls
|
||||
- `terragrunt.hcl` - Stack-specific Terragrunt configuration
|
||||
- `variables.tf` - Variable declarations for a stack
|
||||
- `providers.tf` - Generated by Terragrunt root `terragrunt.hcl`
|
||||
- `backend.tf` - Generated by Terragrunt for state backend configuration
|
||||
|
||||
**Terraform Variables:**
|
||||
- snake_case for variable names: `var.tls_secret_name`, `var.dbaas_root_password`
|
||||
- snake_case for resource names: `resource "kubernetes_namespace" "nextcloud"`
|
||||
- snake_case for local values: `local.tiers`
|
||||
- UPPERCASE for environment-like globals in shell: `KUBECONFIG_PATH`, `PASS_COUNT`
|
||||
|
||||
**Resource/Module Names:**
|
||||
- kebab-case for Kubernetes resources: `nextcloud`, `whiteboard`, `kms-web-page`
|
||||
- Leading underscore for prefixed resource names (internal/private pattern): resource names with underscores are module-internal
|
||||
- Descriptive names matching functionality: `kubernetes_namespace`, `kubernetes_deployment`, `helm_release`
|
||||
|
||||
**Shell Functions:**
|
||||
- snake_case for function names: `parse_args()`, `count_lines()`, `check_nodes()`
|
||||
- CamelCase for utility color variables: `RED`, `GREEN`, `YELLOW`, `BLUE`, `BOLD`, `NC`
|
||||
|
||||
**Go Package/Test Names:**
|
||||
- Package-level test functions: `TestContainsVideoMarkers()`, `TestIsDirectVideoContentType()`
|
||||
- Table-driven test pattern with struct fields: `name`, `body`, `ct`, `want`
|
||||
|
||||
## Code Style
|
||||
|
||||
**Terraform Formatting:**
|
||||
- Use `terraform fmt -recursive` for consistent formatting
|
||||
- No explicit linter/formatter config file (tflint/terraform-lint not present)
|
||||
- Indentation: 2 spaces (standard Terraform convention)
|
||||
- Multi-line strings use heredoc syntax: `<<EOT ... EOT` for YAML/config blocks
|
||||
|
||||
**Bash Script Style:**
|
||||
- Shebang: `#!/usr/bin/env bash`
|
||||
- Safety flags: `set -euo pipefail` (exit on error, undefined vars, pipe failures)
|
||||
- Comments use `# ---` separator for section dividers
|
||||
- Comments use `# ---` for grouping related variables/functions
|
||||
- One-liner functions defined as: `function_name() { [[ condition ]] && action; }`
|
||||
- Multiline functions use explicit function body with local keyword for variables
|
||||
|
||||
**Terraform Style:**
|
||||
- Comments for major sections use `# =============================================================================`
|
||||
- Comments for subsections use `# --------- -------`
|
||||
- Inline comments explain why, not what: `# anything secret is fine` (explaining arbitrary choice)
|
||||
- Module calls include comments above describing purpose: `# --- Core ---`, `# --- dbaas ---`
|
||||
|
||||
## Import Organization
|
||||
|
||||
**Terraform:**
|
||||
- Locals (tier definitions) defined at top of main.tf
|
||||
- Variables declared in order: core/required first, then by feature area (dbaas, traefik, etc.)
|
||||
- Modules called after variables, grouped by functional area with comment headers
|
||||
- Resources defined after modules
|
||||
|
||||
**Go:**
|
||||
- Standard imports from `testing` package
|
||||
- No grouping (single simple import)
|
||||
|
||||
**Bash:**
|
||||
- Source definitions at top (colors, globals, helper functions)
|
||||
- Argument parsing in dedicated `parse_args()` function
|
||||
- Main logic organized by check sections with `section()` calls
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Terraform:**
|
||||
- No explicit error handling (declarative; errors cause apply failure)
|
||||
- Dependency management via `depends_on` for explicit ordering
|
||||
- `dependency` blocks in terragrunt for cross-stack dependencies
|
||||
- `skip_outputs = true` used when only needing ordering, not outputs
|
||||
|
||||
**Bash:**
|
||||
- Inline error checks: `command 2>&1) || { fail "message"; return 0; }`
|
||||
- `set -euo pipefail` prevents silent failures and undefined var issues
|
||||
- Error status captured: `$?` implicit via `||` pattern
|
||||
- Graceful degradation with fallback values or skip-able steps
|
||||
|
||||
**Go:**
|
||||
- Standard testing error reporting: `t.Errorf()` with formatted messages
|
||||
- Table-driven test pattern allows multiple related test cases
|
||||
- Error messages include actual vs expected: `got = %v, want = %v`
|
||||
|
||||
## Logging
|
||||
|
||||
**Framework:** Not formally configured; uses `echo` and `echo -e` for output
|
||||
|
||||
**Bash Logging Patterns:**
|
||||
- Color-coded output with status prefixes: `${BLUE}[INFO]${NC}`, `${GREEN}[PASS]${NC}`, `${YELLOW}[WARN]${NC}`, `${RED}[FAIL]${NC}`
|
||||
- Helper functions: `info()`, `pass()`, `warn()`, `fail()` - each increments counters and respects `--quiet` flag
|
||||
- Section headers: `section()` for verbose output, `section_always()` for always-shown sections
|
||||
- Conditional logging: functions check `$JSON`, `$QUIET` flags and skip output as needed
|
||||
- JSON output option available via `json_add()` for machine-readable logging
|
||||
- Detail strings accumulated in variables for final reporting
|
||||
|
||||
**Terraform Logging:**
|
||||
- Relies on Terraform's built-in CLI output
|
||||
- Human-readable variable values in descriptions (Terraform renders these on errors)
|
||||
|
||||
## Comments
|
||||
|
||||
**When to Comment:**
|
||||
|
||||
Terraform:
|
||||
- Section dividers: Major logical groups separated by `# =============================================================================`
|
||||
- Feature group headers: `# --- Feature Name ---` before variable/module blocks
|
||||
- Commented-out code: Temporarily disabled resources/modules include explanation (e.g., "Do not use until issue #X is solved")
|
||||
- Clarifying arbitrary choices: `# anything secret is fine` explains non-obvious variable usage
|
||||
|
||||
Bash:
|
||||
- Function-level comments: Each check function has purpose on first line
|
||||
- Complex logic: Comments before conditional blocks explain intent
|
||||
- Inline comments for edge cases: `# Skip nodes where metrics are not yet available`
|
||||
- Header comments: Scripts include usage documentation at top
|
||||
|
||||
**JSDoc/TSDoc:**
|
||||
- Not used in this codebase (Terraform, Bash, Go only)
|
||||
|
||||
## Function Design
|
||||
|
||||
**Size:**
|
||||
- Terraform modules typically 20-50 lines for simple services, variable declaration blocks 30-100+ lines
|
||||
- Bash functions average 20-40 lines, check functions 10-30 lines
|
||||
- Go test functions 10-60 lines (table + loop)
|
||||
|
||||
**Parameters:**
|
||||
- Terraform: via `variable` declarations and module input variables
|
||||
- Bash: positional parameters passed via `$1`, `$2`, etc. with validation in `parse_args()`
|
||||
- Go: test functions accept `*testing.T` parameter
|
||||
|
||||
**Return Values:**
|
||||
- Terraform: no explicit returns; resource state is the "return"
|
||||
- Bash: `return 0` for success, implicit via `echo` output for values, status codes for error handling
|
||||
- Go: functions tested for boolean returns or calculated values
|
||||
|
||||
**Variables:**
|
||||
- Terraform: module variables, locals, and resource attributes (computed values)
|
||||
- Bash: Global state tracked via counters (`PASS_COUNT`, `WARN_COUNT`, `FAIL_COUNT`), local variables in functions with `local` keyword
|
||||
- Go: table-driven tests use struct fields (no getter/setter pattern)
|
||||
|
||||
## Module Design
|
||||
|
||||
**Exports:**
|
||||
- Terraform: outputs typically omitted unless another stack depends on them (implicit via dependency blocks)
|
||||
- Modules called with `source = "./modules/<name>"` or `source = "../../modules/kubernetes/<name>"`
|
||||
- Module version pinning used for Terraform registry modules: `version = "0.1.5"`
|
||||
|
||||
**Barrel Files:**
|
||||
- Not applicable (no aggregating re-exports in this codebase)
|
||||
- Directories: `stacks/<service>/` is a unit, `stacks/platform/modules/<service>/` groups related modules
|
||||
|
||||
**Module Organization:**
|
||||
- Single responsibility per module directory
|
||||
- Each module typically contains: `main.tf` (resources) and optional `variables.tf` for input variables
|
||||
- Shared Kubernetes utility modules in `modules/kubernetes/`: `ingress_factory/`, `setup_tls_secret/`
|
||||
- Platform services grouped in `stacks/platform/modules/<service>/`
|
||||
|
||||
## Special Patterns
|
||||
|
||||
**Locals for Configuration:**
|
||||
- Tier definitions centralized as map in locals (each service defines same tiers locally)
|
||||
```hcl
|
||||
locals {
|
||||
tiers = {
|
||||
core = "0-core"
|
||||
cluster = "1-cluster"
|
||||
gpu = "2-gpu"
|
||||
edge = "3-edge"
|
||||
aux = "4-aux"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Tier applied to `kubernetes_namespace` labels and `priority_class_name` for resource governance
|
||||
|
||||
**Inline Config Blocks:**
|
||||
- YAML/config data stored in `<<EOT ... EOT` heredoc blocks within `data` maps
|
||||
- Example: MetalLB address pool config in ConfigMap data
|
||||
|
||||
**File Inclusion:**
|
||||
- `templatefile()` used for dynamic YAML values: `templatefile("${path.module}/chart_values.yaml", { var1 = value })`
|
||||
- `file()` used for static file content in ConfigMap data
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: 2026-02-23*
|
||||
Loading…
Add table
Add a link
Reference in a new issue