Mikkel Georgsen
a639a53b0b
Codebase: 7 documents (stack, architecture, structure, conventions, testing, integrations, concerns) Research: 5 documents (stack, features, architecture, pitfalls, summary)
228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
# 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*
|