# Codebase Structure

**Analysis Date:** 2026-02-04

## Directory Layout

```
/home/mikkel/homelab/
├── .planning/                      # Planning and analysis artifacts
│   └── codebase/                   # Codebase documentation (ARCHITECTURE.md, STRUCTURE.md, etc.)
├── .git/                           # Git repository metadata
├── telegram/                       # Telegram bot and message storage
│   ├── bot.py                      # Main bot implementation
│   ├── credentials                 # Telegram bot token (env var: TELEGRAM_BOT_TOKEN)
│   ├── authorized_users            # Allowlist of chat IDs (one per line)
│   ├── inbox                       # Messages from admin (appended on each message)
│   ├── images/                     # Photos sent via Telegram (timestamped)
│   └── files/                      # Files sent via Telegram (timestamped)
├── pve-homelab-kit/               # PVE installation kit (subproject)
│   ├── install.sh                  # Installation script
│   ├── PROMPT.md                   # Project context for Claude
│   ├── .planning/                  # Subproject planning docs
│   └── README.md                   # Setup instructions
├── npm/                            # Nginx Proxy Manager configuration
│   └── npm-api.conf                # API credentials reference
├── dockge/                         # Docker Compose Manager configuration
│   └── credentials                 # Dockge API access
├── dns/                            # Technitium DNS configuration
│   └── credentials                 # DNS API credentials (env vars: DNS_HOST, DNS_PORT, DNS_USER, DNS_PASS)
├── dns-services/                   # DNS services configuration
│   └── credentials                 # Alternative DNS credentials
├── pve/                            # Proxmox VE configuration
│   └── credentials                 # PVE API credentials (env vars: host, user, token_name, token_value)
├── beszel/                         # Beszel monitoring dashboard
│   ├── credentials                 # Beszel API credentials
│   └── README.md                   # API and agent setup guide
├── forgejo/                        # Forgejo Git server configuration
│   └── credentials                 # Forgejo API access
├── uptime-kuma/                    # Uptime Kuma monitoring
│   ├── credentials                 # Kuma API credentials (env vars: KUMA_HOST, KUMA_PORT, KUMA_API_KEY)
│   ├── README.md                   # REST API reference and Socket.IO documentation
│   └── kuma_api_doc.png            # Full API documentation screenshot
├── README.md                       # Repository overview and service table
├── CLAUDE.md                       # Claude Code guidance and infrastructure quick reference
├── homelab-documentation.md        # Authoritative infrastructure documentation
├── TODO.md                         # Pending maintenance tasks
└── .gitignore                      # Git ignore patterns (credentials, sensitive files)
```

## Directory Purposes

**telegram/:**
- Purpose: Two-way Telegram bot for management commands and admin notifications
- Contains: Python bot code, token credentials, authorized user allowlist, message inbox, uploaded media
- Key files: `bot.py` (407 lines), `credentials`, `authorized_users`, `inbox`
- Not committed: `credentials`, `inbox`, `images/*`, `files/*` (in `.gitignore`)

**pve-homelab-kit/:**
- Purpose: Standalone PVE installation and initial setup toolkit
- Contains: Installation script, configuration examples, planning documents
- Key files: `install.sh` (executable automation), `PROMPT.md` (context for Claude), subproject `.planning/`
- Notes: Separate git repository (submodule or independent), for initial PVE deployment

**npm/:**
- Purpose: Nginx Proxy Manager reverse proxy configuration
- Contains: API credentials reference
- Key files: `npm-api.conf`

**dns/ & dns-services/:**
- Purpose: Technitium DNS server configuration (dual credential sets)
- Contains: API authentication credentials
- Key files: `credentials` (host, port, user, password)

**pve/:**
- Purpose: Proxmox VE API access credentials
- Contains: Token-based authentication data
- Key files: `credentials` (host, user, token_name, token_value)

**dockge/, forgejo/, beszel/, uptime-kuma/:**
- Purpose: Service-specific API credentials and documentation
- Contains: Token/API key for each service
- Key files: `credentials`, service-specific `README.md` (beszel, uptime-kuma)

**homelab-documentation.md:**
- Purpose: Authoritative reference for all infrastructure details
- Contains: Network topology, VM/container registry, service mappings, security rules, firewall config
- Must be updated whenever: services added/removed, IPs changed, configurations modified

**CLAUDE.md:**
- Purpose: Claude Code (AI assistant) guidance and quick reference
- Contains: Environment setup, helper script signatures, API access patterns, security notes
- Auto-loaded by Claude when working in this repository

**.planning/codebase/:**
- Purpose: GSD codebase analysis artifacts
- Will contain: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, STACK.md, INTEGRATIONS.md, CONCERNS.md
- Generated by: GSD codebase mapper, consumed by GSD planner/executor

## Key File Locations

**Entry Points:**
- `telegram/bot.py`: Telegram bot entry point (asyncio-based)
- `pve-homelab-kit/install.sh`: Initial PVE setup entry point

**Configuration:**
- `homelab-documentation.md`: Infrastructure reference (IPs, ports, network topology, firewall rules)
- `CLAUDE.md`: Claude Code environment setup and quick reference
- `.planning/`: Planning and analysis artifacts

**Core Logic:**
- `~/bin/pve`: Proxmox VE API wrapper (Python, 200 lines)
- `~/bin/dns`: Technitium DNS API wrapper (Bash, 107 lines)
- `~/bin/pbs`: PBS backup status and management (Bash, 400+ lines)
- `~/bin/beszel`: Beszel monitoring dashboard API (Bash/Python, 137 lines)
- `~/bin/kuma`: Uptime Kuma monitor management (Bash, 144 lines)
- `~/bin/updates`: Service version checking and updates (Bash, 450+ lines)
- `~/bin/telegram`: CLI helper for Telegram bot control (2-way messaging)
- `~/bin/npm-api`: NPM reverse proxy management (wrapper script)
- `telegram/bot.py`: Telegram bot with command handlers and media management

**Testing:**
- Not applicable (no automated tests in this repository)

## Naming Conventions

**Files:**
- Lowercase with hyphens for multi-word names: `npm-api`, `uptime-kuma`, `pve-homelab-kit`
- Markdown documentation: UPPERCASE.md (`README.md`, `CLAUDE.md`, `homelab-documentation.md`)
- Configuration/credential files: lowercase `credentials` with optional zone prefix

**Directories:**
- Service-specific: lowercase, match service name (`npm`, `dns`, `dockge`, `forgejo`, `beszel`, `telegram`)
- Functional: category name (`pve`, `pve-homelab-kit`)
- Hidden: `.planning`, `.git` for system metadata

**Variables & Parameters:**
- Environment variables: UPPERCASE_WITH_UNDERSCORES (e.g., `TELEGRAM_BOT_TOKEN`, `DNS_HOST`, `KUMA_API_KEY`)
- Bash functions: lowercase_with_underscores (e.g., `get_token()`, `run_command()`, `ssh_pbs()`)
- Python functions: lowercase_with_underscores (e.g., `is_authorized()`, `run_command()`, `get_status()`)

## Where to Add New Code

**New Helper Script (CLI tool):**
- Primary code: `~/bin/{service_name}` (no extension, executable)
- Credentials: `~/.config/{service_name}/credentials`
- Documentation: Top-of-file comment with usage examples
- Language: Bash for shell commands/APIs, Python for complex logic (use Python venv)

**New Service Configuration:**
- Directory: `/home/mikkel/homelab/{service_name}/`
- Credentials file: `{service_name}/credentials`
- Documentation: `{service_name}/README.md` (include API examples and setup)
- Git handling: All credentials in `.gitignore`, document as `credentials.example` if needed

**New Telegram Bot Command:**
- File: `telegram/bot.py` (add function to existing handlers section)
- Pattern: Async function named `cmd_name()`, check authorization first with `is_authorized()`
- Result: Send back via `update.message.reply_text()`
- Timeout: Default 30 seconds (configurable via `run_command()`)

**New Documentation:**
- Infrastructure changes: Update `homelab-documentation.md` (IPs, service registry, network config)
- Claude Code guidance: Update `CLAUDE.md` (new helper scripts, environment setup)
- Service-specific: Create `{service_name}/README.md` with API examples and access patterns

**Shared Utilities:**
- Location: Create in `~/lib/` or `~/venv/lib/` for Python packages
- Access: Import in other scripts or source in Bash

## Special Directories

**.planning/codebase/:**
- Purpose: GSD analysis artifacts
- Generated: Yes (by GSD codebase mapper)
- Committed: Yes (part of repository for reference)

**telegram/images/ & telegram/files/:**
- Purpose: Media uploaded via Telegram bot
- Generated: Yes (bot downloads on receipt)
- Committed: No (in `.gitignore`)

**telegram/inbox:**
- Purpose: Admin messages to Claude
- Generated: Yes (bot appends messages)
- Committed: No (in `.gitignore`)

**.git/**
- Purpose: Git repository metadata
- Generated: Yes (by git)
- Committed: No (system directory)

**pve-homelab-kit/.planning/**
- Purpose: Subproject planning documents
- Generated: Yes (by GSD mapper on subproject)
- Committed: Yes (tracked in subproject)

## Credential File Organization

All credentials stored in `~/.config/{service}/credentials` using key=value format (one per line):

```bash
# ~/.config/pve/credentials
host=core.georgsen.dk
user=root@pam
token_name=automation
token_value=<token-uuid>

# ~/.config/dns/credentials
DNS_HOST=10.5.0.2
DNS_PORT=5380
DNS_USER=admin
DNS_PASS=<password>

# ~/.config/beszel/credentials
BESZEL_HOST=10.5.0.10
BESZEL_PORT=8090
BESZEL_USER=<email>
BESZEL_PASS=<password>
```

**Loading Pattern:**
- Bash: `source ~/.config/{service}/credentials` or inline `$(cat ~/.config/{service}/credentials | grep ^KEY= | cut -d= -f2-)`
- Python: Read file, parse `key=value` lines into dict
- Never hardcode credentials in scripts

---

*Structure analysis: 2026-02-04*