Kalex
Alex & Katy’s unified home management system
Kalex is an orchestration repository that brings together all the tools and services for managing our home infrastructure, budget, and daily life.
Projects
| Project | Description | Repository |
|---|
| kalnet | Home network service mesh (Jellyfin, n8n, Matrix, Sunshine) | k41ex/kalnet |
| kalweb | Unified dashboard (Next.js + shadcn/ui) | k41ex/kalweb |
| kalops | Budget tracking system (Starling → Airtable → n8n) | k41ex/kalops |
Architecture
Figure 1 — Kalex Dashboard Architecture. The KALWEB dashboard fetches service health from KALNET every 15 seconds and budget summaries from KALOPS every 60 seconds through a shared SWR-based fetcher layer. The budget pipeline ingests data from Starling Bank via n8n into Airtable.
| Trace ID | Requirement | Rationale | Test Case |
|---|
KALEX-ARCH-001 | The Kalnet widget shall poll service health every 15 seconds with SWR revalidation | Provides near-real-time service visibility without WebSocket complexity | TC-KALEX-ARCH-001 |
KALEX-ARCH-002 | The budget pipeline shall sync Starling Bank transactions to Airtable via n8n with idempotent upserts | Prevents duplicate transaction records on retries | TC-KALEX-ARCH-002 |
KALEX-ARCH-003 | The shared fetcher layer shall implement exponential backoff retry for all API calls | Gracefully handles transient network failures without cascading errors | TC-KALEX-ARCH-003 |
Data Flow
- Kalnet Widget: Fetches service health from
KALNET_API_URL/api/kalex every 15s
- Budget Widget: Fetches budget summary from
KALOPS_API_URL/api/budget/summary every 60s
- Both widgets use a shared SWR-based fetching layer with error handling and retry logic
- All monetary values are stored in pence (minor units) and formatted client-side
Quick Start
Clone with Submodules
# Clone with all submodules
git clone --recurse-submodules https://github.com/k41ex/kalex.git
cd kalex
# Or if already cloned, initialize submodules
git submodule update --init --recursive
Development (DevContainer)
The easiest way to develop the full stack is using VS Code DevContainers:
# Open in VS Code - it will prompt to reopen in container
code .
- Start all Kalnet services (Jellyfin, n8n, Traefik, metrics collector)
- Install Node.js and Go toolchains
- Set up the development environment
Working with Individual Projects
Each project can be developed independently:
# Kalnet - Home network services
cd kalnet
make wizard # Interactive setup
make up-prod # Start services
# Kalweb - Dashboard
cd kalweb
npm install
npm run dev # http://localhost:3000
# Kalops - Budget system
cd kalops
# Follow MVA_DEVELOPMENT.md
Updating Submodules
# Update all submodules to latest
git submodule update --remote --merge
# Update specific submodule
git submodule update --remote kalnet
Repository Structure
kalex/ # Orchestration repo
├── .devcontainer/ # VS Code DevContainer for full-stack dev
│ ├── devcontainer.json
│ ├── docker-compose.yml
│ └── Dockerfile
├── .gitmodules # Submodule definitions
├── kalnet/ # → submodule: k41ex/kalnet
├── kalweb/ # → submodule: k41ex/kalweb
├── kalops/ # → submodule: k41ex/kalops
├── README.md # This file
└── LICENSE
Requirements
Hardware
- 16GB+ RAM (for running full stack)
- AMD GPU (for VAAPI/AMF hardware encoding)
- 100GB+ storage (more for media)
Software
- Docker 24.0+
- Docker Compose 2.20+
- Git with submodule support
- Node.js 20+ (for kalweb)
- Go 1.22+ (for kalnet development)
Documentation
Organized documentation is available:
Contributing
- Fork the relevant component repository
- Create a feature branch
- Make your changes
- Submit a PR to the component repo
For changes affecting multiple components, coordinate PRs across repos.
License
MIT License - see LICENSE for details.
Kalex - Home Life, Unified
