Skip to main content

​
Kalex

Alex & Katy’s unified home management system
License: MIT Kalex is an orchestration repository that brings together all the tools and services for managing our home infrastructure, budget, and daily life.

​
Projects

ProjectDescriptionRepository
kalnetHome network service mesh (Jellyfin, n8n, Matrix, Sunshine)k41ex/kalnet
kalwebUnified dashboard (Next.js + shadcn/ui)k41ex/kalweb
kalopsBudget tracking system (Starling → Airtable → n8n)k41ex/kalops

​
Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                              KALWEB                                       │
│                   Unified Dashboard (Next.js + SWR)                       │
│                                                                           │
│    ┌────────────────┐  ┌────────────────┐  ┌──────────┐  ┌──────────┐   │
│    │  KalnetWidget  │  │  BudgetWidget  │  │ Calendar │  │  Tasks   │   │
│    │  (15s refresh) │  │  (60s refresh) │  │  Widget  │  │  Widget  │   │
│    └───────┬────────┘  └───────┬────────┘  └──────────┘  └──────────┘   │
│            │                   │                                          │
│            │    ┌──────────────┴──────────────┐                          │
│            │    │     useBudgetData (SWR)     │                          │
│            │    │  • BudgetOverview           │                          │
│            │    │  • CategoryList             │                          │
│            │    │  • RecentTransactions       │                          │
│            │    │  • AlertBadge               │                          │
│            │    └──────────────┬──────────────┘                          │
│            │                   │                                          │
│    ┌───────┴───────────────────┴───────┐                                 │
│    │        Shared Fetcher Layer        │                                 │
│    │   (Error handling, retry logic)    │                                 │
│    └───────┬───────────────────┬───────┘                                 │
└────────────┼───────────────────┼─────────────────────────────────────────┘
             │                   │
             │ GET /api/kalex    │ GET /api/budget/summary
             ▼                   ▼
┌─────────────────────┐  ┌─────────────────────┐
│       KALNET        │  │       KALOPS        │
│    Home Network     │  │    Budget System    │
│                     │  │                     │
│  • Jellyfin         │  │  /api/budget/       │
│  • n8n              │  │    └─ summary       │
│  • Matrix           │  │                     │
│  • Sunshine         │  │  Data Pipeline:     │
│  • Traefik          │  │  Starling Bank API  │
│                     │  │       ↓             │
│  /api/kalex:        │  │  n8n Workflows      │
│  Returns service    │  │       ↓             │
│  health metrics     │  │  Airtable (storage) │
└─────────────────────┘  └─────────────────────┘

​
Data Flow

  1. Kalnet Widget: Fetches service health from KALNET_API_URL/api/kalex every 15s
  2. Budget Widget: Fetches budget summary from KALOPS_API_URL/api/budget/summary every 60s
  3. Both widgets use a shared SWR-based fetching layer with error handling and retry logic
  4. 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 .
The DevContainer will:
  • 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

  1. Fork the relevant component repository
  2. Create a feature branch
  3. Make your changes
  4. 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