homelab/.planning/codebase/STRUCTURE.md

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):

# ~/.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