jfraeysd/fetch_ml
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
fetch_ml/docs/_site/architecture/index.html
Jeremie Fraeys ea15af1833 Fix multi-user authentication and clean up debug code 
- Fix YAML tags in auth config struct (json -> yaml)
- Update CLI configs to use pre-hashed API keys
- Remove double hashing in WebSocket client
- Fix port mapping (9102 -> 9103) in CLI commands
- Update permission keys to use jobs:read, jobs:create, etc.
- Clean up all debug logging from CLI and server
- All user roles now authenticate correctly:
  * Admin: Can queue jobs and see all jobs
  * Researcher: Can queue jobs and see own jobs
  * Analyst: Can see status (read-only access)

Multi-user authentication is now fully functional.
2025-12-06 12:35:32 -05:00

3055 lines
No EOL
71 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Secure Machine Learning Platform">
<link rel="prev" href="../testing/">
<link rel="next" href="../cli-reference/">
<link rel="icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.0">
<title>Homelab Architecture - Fetch ML Documentation</title>
<link rel="stylesheet" href="../assets/stylesheets/main.618322db.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="blue" data-md-color-accent="blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#homelab-architecture" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="Fetch ML Documentation" class="md-header__button md-logo" aria-label="Fetch ML Documentation" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Fetch ML Documentation
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Homelab Architecture
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="blue" data-md-color-accent="blue" aria-hidden="true" type="radio" name="__palette" id="__palette_0">
<input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="blue" data-md-color-accent="blue" aria-hidden="true" type="radio" name="__palette" id="__palette_1">
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/jfraeys/fetch_ml" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../quick-start/" class="md-tabs__link">
Getting Started
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../development-setup/" class="md-tabs__link">
Development
</a>
</li>
<li class="md-tabs__item">
<a href="../deployment/" class="md-tabs__link">
Operations & Production
</a>
</li>
<li class="md-tabs__item">
<a href="../security/" class="md-tabs__link">
Security
</a>
</li>
<li class="md-tabs__item">
<a href="../configuration-schema/" class="md-tabs__link">
Reference
</a>
</li>
<li class="md-tabs__item">
<a href="../adr/" class="md-tabs__link">
Architecture Decisions
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted md-nav--integrated" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="Fetch ML Documentation" class="md-nav__button md-logo" aria-label="Fetch ML Documentation" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
Fetch ML Documentation
</label>
<div class="md-nav__source">
<a href="https://github.com/jfraeys/fetch_ml" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2" >
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
<span class="md-ellipsis">
Getting Started
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Getting Started
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../quick-start/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../installation/" class="md-nav__link">
<span class="md-ellipsis">
Simple Installation Guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../first-experiment/" class="md-nav__link">
<span class="md-ellipsis">
First Experiment
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
Development
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Development
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../development-setup/" class="md-nav__link">
<span class="md-ellipsis">
Development Setup
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../testing/" class="md-nav__link">
<span class="md-ellipsis">
Testing Guide
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Homelab Architecture
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Homelab Architecture
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#components-overview" class="md-nav__link">
<span class="md-ellipsis">
Components Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#core-services" class="md-nav__link">
<span class="md-ellipsis">
Core Services
</span>
</a>
<nav class="md-nav" aria-label="Core Services">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#api-server" class="md-nav__link">
<span class="md-ellipsis">
API Server
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#redis" class="md-nav__link">
<span class="md-ellipsis">
Redis
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#zig-cli" class="md-nav__link">
<span class="md-ellipsis">
Zig CLI
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#security-architecture" class="md-nav__link">
<span class="md-ellipsis">
Security Architecture
</span>
</a>
<nav class="md-nav" aria-label="Security Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#security-layers" class="md-nav__link">
<span class="md-ellipsis">
Security Layers
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#data-flow" class="md-nav__link">
<span class="md-ellipsis">
Data Flow
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#deployment-options" class="md-nav__link">
<span class="md-ellipsis">
Deployment Options
</span>
</a>
<nav class="md-nav" aria-label="Deployment Options">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#docker-compose-recommended" class="md-nav__link">
<span class="md-ellipsis">
Docker Compose (Recommended)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#local-setup" class="md-nav__link">
<span class="md-ellipsis">
Local Setup
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#network-architecture" class="md-nav__link">
<span class="md-ellipsis">
Network Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#storage-architecture" class="md-nav__link">
<span class="md-ellipsis">
Storage Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#monitoring-architecture" class="md-nav__link">
<span class="md-ellipsis">
Monitoring Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#homelab-benefits" class="md-nav__link">
<span class="md-ellipsis">
Homelab Benefits
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#high-level-architecture" class="md-nav__link">
<span class="md-ellipsis">
High-Level Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#zig-cli-architecture" class="md-nav__link">
<span class="md-ellipsis">
Zig CLI Architecture
</span>
</a>
<nav class="md-nav" aria-label="Zig CLI Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#component-structure" class="md-nav__link">
<span class="md-ellipsis">
Component Structure
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#performance-optimizations" class="md-nav__link">
<span class="md-ellipsis">
Performance Optimizations
</span>
</a>
<nav class="md-nav" aria-label="Performance Optimizations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#content-addressed-storage" class="md-nav__link">
<span class="md-ellipsis">
Content-Addressed Storage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#memory-management" class="md-nav__link">
<span class="md-ellipsis">
Memory Management
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#network-communication" class="md-nav__link">
<span class="md-ellipsis">
Network Communication
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#security-implementation" class="md-nav__link">
<span class="md-ellipsis">
Security Implementation
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#core-components" class="md-nav__link">
<span class="md-ellipsis">
Core Components
</span>
</a>
<nav class="md-nav" aria-label="Core Components">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#1-authentication-authorization" class="md-nav__link">
<span class="md-ellipsis">
1. Authentication &amp; Authorization
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#2-worker-service" class="md-nav__link">
<span class="md-ellipsis">
2. Worker Service
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#3-data-manager-service" class="md-nav__link">
<span class="md-ellipsis">
3. Data Manager Service
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#4-terminal-ui-tui" class="md-nav__link">
<span class="md-ellipsis">
4. Terminal UI (TUI)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#data-flow_1" class="md-nav__link">
<span class="md-ellipsis">
Data Flow
</span>
</a>
<nav class="md-nav" aria-label="Data Flow">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#job-execution-flow" class="md-nav__link">
<span class="md-ellipsis">
Job Execution Flow
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#authentication-flow" class="md-nav__link">
<span class="md-ellipsis">
Authentication Flow
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#security-architecture_1" class="md-nav__link">
<span class="md-ellipsis">
Security Architecture
</span>
</a>
<nav class="md-nav" aria-label="Security Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#defense-in-depth" class="md-nav__link">
<span class="md-ellipsis">
Defense in Depth
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#container-security" class="md-nav__link">
<span class="md-ellipsis">
Container Security
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#configuration-architecture" class="md-nav__link">
<span class="md-ellipsis">
Configuration Architecture
</span>
</a>
<nav class="md-nav" aria-label="Configuration Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#configuration-hierarchy" class="md-nav__link">
<span class="md-ellipsis">
Configuration Hierarchy
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#scalability-architecture" class="md-nav__link">
<span class="md-ellipsis">
Scalability Architecture
</span>
</a>
<nav class="md-nav" aria-label="Scalability Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#horizontal-scaling" class="md-nav__link">
<span class="md-ellipsis">
Horizontal Scaling
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#technology-stack" class="md-nav__link">
<span class="md-ellipsis">
Technology Stack
</span>
</a>
<nav class="md-nav" aria-label="Technology Stack">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#backend-technologies" class="md-nav__link">
<span class="md-ellipsis">
Backend Technologies
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#dependencies" class="md-nav__link">
<span class="md-ellipsis">
Dependencies
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#development-architecture" class="md-nav__link">
<span class="md-ellipsis">
Development Architecture
</span>
</a>
<nav class="md-nav" aria-label="Development Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#project-structure" class="md-nav__link">
<span class="md-ellipsis">
Project Structure
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#package-dependencies" class="md-nav__link">
<span class="md-ellipsis">
Package Dependencies
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#monitoring-observability" class="md-nav__link">
<span class="md-ellipsis">
Monitoring &amp; Observability
</span>
</a>
<nav class="md-nav" aria-label="Monitoring &amp; Observability">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#metrics-collection" class="md-nav__link">
<span class="md-ellipsis">
Metrics Collection
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#logging-architecture" class="md-nav__link">
<span class="md-ellipsis">
Logging Architecture
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#deployment-architecture" class="md-nav__link">
<span class="md-ellipsis">
Deployment Architecture
</span>
</a>
<nav class="md-nav" aria-label="Deployment Architecture">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#container-deployment" class="md-nav__link">
<span class="md-ellipsis">
Container Deployment
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#service-discovery" class="md-nav__link">
<span class="md-ellipsis">
Service Discovery
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#future-architecture-considerations" class="md-nav__link">
<span class="md-ellipsis">
Future Architecture Considerations
</span>
</a>
<nav class="md-nav" aria-label="Future Architecture Considerations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#microservices-evolution" class="md-nav__link">
<span class="md-ellipsis">
Microservices Evolution
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#homelab-features" class="md-nav__link">
<span class="md-ellipsis">
Homelab Features
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../cli-reference/" class="md-nav__link">
<span class="md-ellipsis">
CLI Reference
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../zig-cli/" class="md-nav__link">
<span class="md-ellipsis">
Zig CLI Guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../queue/" class="md-nav__link">
<span class="md-ellipsis">
Task Queue Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../smart-defaults/" class="md-nav__link">
<span class="md-ellipsis">
Smart Defaults
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cicd/" class="md-nav__link">
<span class="md-ellipsis">
CI/CD Pipeline
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
Operations & Production
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Operations & Production
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../deployment/" class="md-nav__link">
<span class="md-ellipsis">
ML Experiment Manager - Deployment Guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../environment-variables/" class="md-nav__link">
<span class="md-ellipsis">
Environment Variables
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../production-monitoring/" class="md-nav__link">
<span class="md-ellipsis">
Production Monitoring Deployment Guide (Linux)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../operations/" class="md-nav__link">
<span class="md-ellipsis">
Operations Runbook
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../redis-ha/" class="md-nav__link">
<span class="md-ellipsis">
Redis High Availability (Optional)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../release-checklist/" class="md-nav__link">
<span class="md-ellipsis">
Release Checklist
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Security
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Security
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../security/" class="md-nav__link">
<span class="md-ellipsis">
Security Guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api-key-process/" class="md-nav__link">
<span class="md-ellipsis">
FetchML API Key Process
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../user-permissions/" class="md-nav__link">
<span class="md-ellipsis">
User Permissions in Fetch ML
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
<span class="md-ellipsis">
Reference
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Reference
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../configuration-schema/" class="md-nav__link">
<span class="md-ellipsis">
Configuration Schema
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../troubleshooting/" class="md-nav__link">
<span class="md-ellipsis">
Troubleshooting
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_7" >
<div class="md-nav__link md-nav__container">
<a href="../adr/" class="md-nav__link ">
<span class="md-ellipsis">
Architecture Decisions
</span>
</a>
<label class="md-nav__link " for="__nav_7" id="__nav_7_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_7">
<span class="md-nav__icon md-icon"></span>
Architecture Decisions
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../adr/ADR-001-use-go-for-api-server/" class="md-nav__link">
<span class="md-ellipsis">
ADR-001: Use Go for API Server
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../adr/ADR-002-use-sqlite-for-local-development/" class="md-nav__link">
<span class="md-ellipsis">
ADR-002: Use SQLite for Local Development
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../adr/ADR-003-use-redis-for-job-queue/" class="md-nav__link">
<span class="md-ellipsis">
ADR-003: Use Redis for Job Queue
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="homelab-architecture">Homelab Architecture<a class="headerlink" href="#homelab-architecture" title="Permanent link">&para;</a></h1>
<p>Simple, secure architecture for ML experiments in your homelab.</p>
<h2 id="components-overview">Components Overview<a class="headerlink" href="#components-overview" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Homelab Stack&quot;
CLI[Zig CLI]
API[HTTPS API]
REDIS[Redis Cache]
FS[Local Storage]
end
CLI --&gt; API
API --&gt; REDIS
API --&gt; FS
</code></pre></div>
<h2 id="core-services">Core Services<a class="headerlink" href="#core-services" title="Permanent link">&para;</a></h2>
<h3 id="api-server">API Server<a class="headerlink" href="#api-server" title="Permanent link">&para;</a></h3>
<ul>
<li><strong>Purpose</strong>: Secure HTTPS API for ML experiments</li>
<li><strong>Port</strong>: 9101 (HTTPS only)</li>
<li><strong>Auth</strong>: API key authentication</li>
<li><strong>Security</strong>: Rate limiting, IP whitelisting</li>
</ul>
<h3 id="redis">Redis<a class="headerlink" href="#redis" title="Permanent link">&para;</a></h3>
<ul>
<li><strong>Purpose</strong>: Caching and job queuing</li>
<li><strong>Port</strong>: 6379 (localhost only)</li>
<li><strong>Storage</strong>: Temporary data only</li>
<li><strong>Persistence</strong>: Local volume</li>
</ul>
<h3 id="zig-cli">Zig CLI<a class="headerlink" href="#zig-cli" title="Permanent link">&para;</a></h3>
<ul>
<li><strong>Purpose</strong>: High-performance experiment management</li>
<li><strong>Language</strong>: Zig for maximum speed and efficiency</li>
<li><strong>Features</strong>:</li>
<li>Content-addressed storage with deduplication</li>
<li>SHA256-based commit ID generation</li>
<li>WebSocket communication for real-time updates</li>
<li>Rsync-based incremental file transfers</li>
<li>Multi-threaded operations</li>
<li>Secure API key authentication</li>
<li>Auto-sync monitoring with file system watching</li>
<li>Priority-based job queuing</li>
<li>Memory-efficient operations with arena allocators</li>
</ul>
<h2 id="security-architecture">Security Architecture<a class="headerlink" href="#security-architecture" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code>graph LR
USER[User] --&gt; AUTH[API Key Auth]
AUTH --&gt; RATE[Rate Limiting]
RATE --&gt; WHITELIST[IP Whitelist]
WHITELIST --&gt; API[Secure API]
API --&gt; AUDIT[Audit Logging]
</code></pre></div>
<h3 id="security-layers">Security Layers<a class="headerlink" href="#security-layers" title="Permanent link">&para;</a></h3>
<ol>
<li><strong>API Key Authentication</strong> - Hashed keys with roles</li>
<li><strong>Rate Limiting</strong> - 30 requests/minute</li>
<li><strong>IP Whitelisting</strong> - Local networks only</li>
<li><strong>Fail2Ban</strong> - Automatic IP blocking</li>
<li><strong>HTTPS/TLS</strong> - Encrypted communication</li>
<li><strong>Audit Logging</strong> - Complete action tracking</li>
</ol>
<h2 id="data-flow">Data Flow<a class="headerlink" href="#data-flow" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code>sequenceDiagram
participant CLI
participant API
participant Redis
participant Storage
CLI-&gt;&gt;API: HTTPS Request
API-&gt;&gt;API: Validate Auth
API-&gt;&gt;Redis: Cache/Queue
API-&gt;&gt;Storage: Experiment Data
Storage-&gt;&gt;API: Results
API-&gt;&gt;CLI: Response
</code></pre></div>
<h2 id="deployment-options">Deployment Options<a class="headerlink" href="#deployment-options" title="Permanent link">&para;</a></h2>
<h3 id="docker-compose-recommended">Docker Compose (Recommended)<a class="headerlink" href="#docker-compose-recommended" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code><span class="nt">services</span><span class="p">:</span>
<span class="w"> </span><span class="nt">redis</span><span class="p">:</span>
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis:7-alpine</span>
<span class="w"> </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;6379:6379&quot;</span><span class="p p-Indicator">]</span>
<span class="w"> </span><span class="nt">volumes</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">redis_data</span><span class="p p-Indicator">:</span><span class="nv">/data</span><span class="p p-Indicator">]</span>
<span class="w"> </span><span class="nt">api-server</span><span class="p">:</span>
<span class="w"> </span><span class="nt">build</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.</span>
<span class="w"> </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;9101:9101&quot;</span><span class="p p-Indicator">]</span>
<span class="w"> </span><span class="nt">depends_on</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">redis</span><span class="p p-Indicator">]</span>
</code></pre></div>
<h3 id="local-setup">Local Setup<a class="headerlink" href="#local-setup" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>./setup.sh<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>./manage.sh<span class="w"> </span>start
</code></pre></div>
<h2 id="network-architecture">Network Architecture<a class="headerlink" href="#network-architecture" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Private Network</strong>: Docker internal network</li>
<li><strong>Localhost Access</strong>: Redis only on localhost</li>
<li><strong>HTTPS API</strong>: Port 9101, TLS encrypted</li>
<li><strong>No External Dependencies</strong>: Everything runs locally</li>
</ul>
<h2 id="storage-architecture">Storage Architecture<a class="headerlink" href="#storage-architecture" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code>data/
├── experiments/ # ML experiment results
├── cache/ # Temporary cache files
└── backups/ # Local backups
logs/
├── app.log # Application logs
├── audit.log # Security events
└── access.log # API access logs
</code></pre></div>
<h2 id="monitoring-architecture">Monitoring Architecture<a class="headerlink" href="#monitoring-architecture" title="Permanent link">&para;</a></h2>
<p>Simple, lightweight monitoring:
- <strong>Health Checks</strong>: Service availability
- <strong>Log Files</strong>: Structured logging
- <strong>Basic Metrics</strong>: Request counts, error rates
- <strong>Security Events</strong>: Failed auth, rate limits</p>
<h2 id="homelab-benefits">Homelab Benefits<a class="headerlink" href="#homelab-benefits" title="Permanent link">&para;</a></h2>
<ul>
<li>✅ <strong>Simple Setup</strong>: One-command installation</li>
<li>✅ <strong>Local Only</strong>: No external dependencies</li>
<li>✅ <strong>Secure by Default</strong>: HTTPS, auth, rate limiting</li>
<li>✅ <strong>Low Resource</strong>: Minimal CPU/memory usage</li>
<li>✅ <strong>Easy Backup</strong>: Local file system</li>
<li>✅ <strong>Privacy</strong>: Everything stays on your network</li>
</ul>
<h2 id="high-level-architecture">High-Level Architecture<a class="headerlink" href="#high-level-architecture" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Client Layer&quot;
CLI[CLI Tools]
TUI[Terminal UI]
API[REST API]
end
subgraph &quot;Authentication Layer&quot;
Auth[Authentication Service]
RBAC[Role-Based Access Control]
Perm[Permission Manager]
end
subgraph &quot;Core Services&quot;
Worker[ML Worker Service]
DataMgr[Data Manager Service]
Queue[Job Queue]
end
subgraph &quot;Storage Layer&quot;
Redis[(Redis Cache)]
DB[(SQLite/PostgreSQL)]
Files[File Storage]
end
subgraph &quot;Container Runtime&quot;
Podman[Podman/Docker]
Containers[ML Containers]
end
CLI --&gt; Auth
TUI --&gt; Auth
API --&gt; Auth
Auth --&gt; RBAC
RBAC --&gt; Perm
Worker --&gt; Queue
Worker --&gt; DataMgr
Worker --&gt; Podman
DataMgr --&gt; DB
DataMgr --&gt; Files
Queue --&gt; Redis
Podman --&gt; Containers
</code></pre></div>
<h2 id="zig-cli-architecture">Zig CLI Architecture<a class="headerlink" href="#zig-cli-architecture" title="Permanent link">&para;</a></h2>
<h3 id="component-structure">Component Structure<a class="headerlink" href="#component-structure" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Zig CLI Components&quot;
Main[main.zig] --&gt; Commands[commands/]
Commands --&gt; Config[config.zig]
Commands --&gt; Utils[utils/]
Commands --&gt; Net[net/]
Commands --&gt; Errors[errors.zig]
subgraph &quot;Commands&quot;
Init[init.zig]
Sync[sync.zig]
Queue[queue.zig]
Watch[watch.zig]
Status[status.zig]
Monitor[monitor.zig]
Cancel[cancel.zig]
Prune[prune.zig]
end
subgraph &quot;Utils&quot;
Crypto[crypto.zig]
Storage[storage.zig]
Rsync[rsync.zig]
end
subgraph &quot;Network&quot;
WS[ws.zig]
end
end
</code></pre></div>
<h3 id="performance-optimizations">Performance Optimizations<a class="headerlink" href="#performance-optimizations" title="Permanent link">&para;</a></h3>
<h4 id="content-addressed-storage">Content-Addressed Storage<a class="headerlink" href="#content-addressed-storage" title="Permanent link">&para;</a></h4>
<ul>
<li><strong>Deduplication</strong>: Files stored by SHA256 hash</li>
<li><strong>Space Efficiency</strong>: Shared files across experiments</li>
<li><strong>Fast Lookup</strong>: Hash-based file retrieval</li>
</ul>
<h4 id="memory-management">Memory Management<a class="headerlink" href="#memory-management" title="Permanent link">&para;</a></h4>
<ul>
<li><strong>Arena Allocators</strong>: Efficient bulk allocation</li>
<li><strong>Zero-Copy Operations</strong>: Minimized memory copying</li>
<li><strong>Automatic Cleanup</strong>: Resource deallocation</li>
</ul>
<h4 id="network-communication">Network Communication<a class="headerlink" href="#network-communication" title="Permanent link">&para;</a></h4>
<ul>
<li><strong>WebSocket Protocol</strong>: Real-time bidirectional communication</li>
<li><strong>Connection Pooling</strong>: Reused connections</li>
<li><strong>Binary Messaging</strong>: Efficient data transfer</li>
</ul>
<h3 id="security-implementation">Security Implementation<a class="headerlink" href="#security-implementation" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph LR
subgraph &quot;CLI Security&quot;
Config[Config File] --&gt; Hash[SHA256 Hashing]
Hash --&gt; Auth[API Authentication]
Auth --&gt; SSH[SSH Transfer]
SSH --&gt; WS[WebSocket Security]
end
</code></pre></div>
<h2 id="core-components">Core Components<a class="headerlink" href="#core-components" title="Permanent link">&para;</a></h2>
<h3 id="1-authentication-authorization">1. Authentication &amp; Authorization<a class="headerlink" href="#1-authentication-authorization" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph LR
subgraph &quot;Auth Flow&quot;
Client[Client] --&gt; APIKey[API Key]
APIKey --&gt; Hash[Hash Validation]
Hash --&gt; Roles[Role Resolution]
Roles --&gt; Perms[Permission Check]
Perms --&gt; Access[Grant/Deny Access]
end
subgraph &quot;Permission Sources&quot;
YAML[YAML Config]
Inline[Inline Fallback]
Roles --&gt; YAML
Roles --&gt; Inline
end
</code></pre></div>
<p><strong>Features:</strong>
- API key-based authentication
- Role-based access control (RBAC)
- YAML-based permission configuration
- Fallback to inline permissions
- Admin wildcard permissions</p>
<h3 id="2-worker-service">2. Worker Service<a class="headerlink" href="#2-worker-service" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Worker Architecture&quot;
API[HTTP API] --&gt; Router[Request Router]
Router --&gt; Auth[Auth Middleware]
Auth --&gt; Queue[Job Queue]
Queue --&gt; Processor[Job Processor]
Processor --&gt; Runtime[Container Runtime]
Runtime --&gt; Storage[Result Storage]
subgraph &quot;Job Lifecycle&quot;
Submit[Submit Job] --&gt; Queue
Queue --&gt; Execute[Execute]
Execute --&gt; Monitor[Monitor]
Monitor --&gt; Complete[Complete]
Complete --&gt; Store[Store Results]
end
end
</code></pre></div>
<p><strong>Responsibilities:</strong>
- HTTP API for job submission
- Job queue management
- Container orchestration
- Result collection and storage
- Metrics and monitoring</p>
<h3 id="3-data-manager-service">3. Data Manager Service<a class="headerlink" href="#3-data-manager-service" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Data Management&quot;
API[Data API] --&gt; Storage[Storage Layer]
Storage --&gt; Metadata[Metadata DB]
Storage --&gt; Files[File System]
Storage --&gt; Cache[Redis Cache]
subgraph &quot;Data Operations&quot;
Upload[Upload Data] --&gt; Validate[Validate]
Validate --&gt; Store[Store]
Store --&gt; Index[Index]
Index --&gt; Catalog[Catalog]
end
end
</code></pre></div>
<p><strong>Features:</strong>
- Data upload and validation
- Metadata management
- File system abstraction
- Caching layer
- Data catalog</p>
<h3 id="4-terminal-ui-tui">4. Terminal UI (TUI)<a class="headerlink" href="#4-terminal-ui-tui" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;TUI Architecture&quot;
UI[UI Components] --&gt; Model[Data Model]
Model --&gt; Update[Update Loop]
Update --&gt; Render[Render]
subgraph &quot;UI Panels&quot;
Jobs[Job List]
Details[Job Details]
Logs[Log Viewer]
Status[Status Bar]
end
UI --&gt; Jobs
UI --&gt; Details
UI --&gt; Logs
UI --&gt; Status
end
</code></pre></div>
<p><strong>Components:</strong>
- Bubble Tea framework
- Component-based architecture
- Real-time updates
- Keyboard navigation
- Theme support</p>
<h2 id="data-flow_1">Data Flow<a class="headerlink" href="#data-flow_1" title="Permanent link">&para;</a></h2>
<h3 id="job-execution-flow">Job Execution Flow<a class="headerlink" href="#job-execution-flow" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>sequenceDiagram
participant Client
participant Auth
participant Worker
participant Queue
participant Container
participant Storage
Client-&gt;&gt;Auth: Submit job with API key
Auth-&gt;&gt;Client: Validate and return job ID
Client-&gt;&gt;Worker: Execute job request
Worker-&gt;&gt;Queue: Queue job
Queue-&gt;&gt;Worker: Job ready
Worker-&gt;&gt;Container: Start ML container
Container-&gt;&gt;Worker: Execute experiment
Worker-&gt;&gt;Storage: Store results
Worker-&gt;&gt;Client: Return results
</code></pre></div>
<h3 id="authentication-flow">Authentication Flow<a class="headerlink" href="#authentication-flow" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>sequenceDiagram
participant Client
participant Auth
participant PermMgr
participant Config
Client-&gt;&gt;Auth: Request with API key
Auth-&gt;&gt;Auth: Validate key hash
Auth-&gt;&gt;PermMgr: Get user permissions
PermMgr-&gt;&gt;Config: Load YAML permissions
Config-&gt;&gt;PermMgr: Return permissions
PermMgr-&gt;&gt;Auth: Return resolved permissions
Auth-&gt;&gt;Client: Grant/deny access
</code></pre></div>
<h2 id="security-architecture_1">Security Architecture<a class="headerlink" href="#security-architecture_1" title="Permanent link">&para;</a></h2>
<h3 id="defense-in-depth">Defense in Depth<a class="headerlink" href="#defense-in-depth" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Security Layers&quot;
Network[Network Security]
Auth[Authentication]
AuthZ[Authorization]
Container[Container Security]
Data[Data Protection]
Audit[Audit Logging]
end
Network --&gt; Auth
Auth --&gt; AuthZ
AuthZ --&gt; Container
Container --&gt; Data
Data --&gt; Audit
</code></pre></div>
<p><strong>Security Features:</strong>
- API key authentication
- Role-based permissions
- Container isolation
- File system sandboxing
- Comprehensive audit logs
- Input validation and sanitization</p>
<h3 id="container-security">Container Security<a class="headerlink" href="#container-security" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Container Isolation&quot;
Host[Host System]
Podman[Podman Runtime]
Network[Network Isolation]
FS[File System Isolation]
User[User Namespaces]
ML[ML Container]
Host --&gt; Podman
Podman --&gt; Network
Podman --&gt; FS
Podman --&gt; User
User --&gt; ML
end
</code></pre></div>
<p><strong>Isolation Features:</strong>
- Rootless containers
- Network isolation
- File system sandboxing
- User namespace mapping
- Resource limits</p>
<h2 id="configuration-architecture">Configuration Architecture<a class="headerlink" href="#configuration-architecture" title="Permanent link">&para;</a></h2>
<h3 id="configuration-hierarchy">Configuration Hierarchy<a class="headerlink" href="#configuration-hierarchy" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Config Sources&quot;
Env[Environment Variables]
File[Config Files]
CLI[CLI Flags]
Defaults[Default Values]
end
subgraph &quot;Config Processing&quot;
Merge[Config Merger]
Validate[Schema Validator]
Apply[Config Applier]
end
Env --&gt; Merge
File --&gt; Merge
CLI --&gt; Merge
Defaults --&gt; Merge
Merge --&gt; Validate
Validate --&gt; Apply
</code></pre></div>
<p><strong>Configuration Priority:</strong>
1. CLI flags (highest)
2. Environment variables
3. Configuration files
4. Default values (lowest)</p>
<h2 id="scalability-architecture">Scalability Architecture<a class="headerlink" href="#scalability-architecture" title="Permanent link">&para;</a></h2>
<h3 id="horizontal-scaling">Horizontal Scaling<a class="headerlink" href="#horizontal-scaling" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Scaled Architecture&quot;
LB[Load Balancer]
W1[Worker 1]
W2[Worker 2]
W3[Worker N]
Redis[Redis Cluster]
Storage[Shared Storage]
LB --&gt; W1
LB --&gt; W2
LB --&gt; W3
W1 --&gt; Redis
W2 --&gt; Redis
W3 --&gt; Redis
W1 --&gt; Storage
W2 --&gt; Storage
W3 --&gt; Storage
end
</code></pre></div>
<p><strong>Scaling Features:</strong>
- Stateless worker services
- Shared job queue (Redis)
- Distributed storage
- Load balancer ready
- Health checks and monitoring</p>
<h2 id="technology-stack">Technology Stack<a class="headerlink" href="#technology-stack" title="Permanent link">&para;</a></h2>
<h3 id="backend-technologies">Backend Technologies<a class="headerlink" href="#backend-technologies" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Component</th>
<th>Technology</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Language</strong></td>
<td>Go 1.25+</td>
<td>Core application</td>
</tr>
<tr>
<td><strong>Web Framework</strong></td>
<td>Standard library</td>
<td>HTTP server</td>
</tr>
<tr>
<td><strong>Authentication</strong></td>
<td>Custom</td>
<td>API key + RBAC</td>
</tr>
<tr>
<td><strong>Database</strong></td>
<td>SQLite/PostgreSQL</td>
<td>Metadata storage</td>
</tr>
<tr>
<td><strong>Cache</strong></td>
<td>Redis</td>
<td>Job queue &amp; caching</td>
</tr>
<tr>
<td><strong>Containers</strong></td>
<td>Podman/Docker</td>
<td>Job isolation</td>
</tr>
<tr>
<td><strong>UI Framework</strong></td>
<td>Bubble Tea</td>
<td>Terminal UI</td>
</tr>
</tbody>
</table>
<h3 id="dependencies">Dependencies<a class="headerlink" href="#dependencies" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code><span class="c1">// Core dependencies</span>
<span class="nx">require</span><span class="w"> </span><span class="p">(</span>
<span class="w"> </span><span class="nx">github</span><span class="p">.</span><span class="nx">com</span><span class="o">/</span><span class="nx">charmbracelet</span><span class="o">/</span><span class="nx">bubbletea</span><span class="w"> </span><span class="nx">v1</span><span class="mf">.3.10</span><span class="w"> </span><span class="c1">// TUI framework</span>
<span class="w"> </span><span class="nx">github</span><span class="p">.</span><span class="nx">com</span><span class="o">/</span><span class="k">go</span><span class="o">-</span><span class="nx">redis</span><span class="o">/</span><span class="nx">redis</span><span class="o">/</span><span class="nx">v8</span><span class="w"> </span><span class="nx">v8</span><span class="mf">.11.5</span><span class="w"> </span><span class="c1">// Redis client</span>
<span class="w"> </span><span class="nx">github</span><span class="p">.</span><span class="nx">com</span><span class="o">/</span><span class="nx">google</span><span class="o">/</span><span class="nx">uuid</span><span class="w"> </span><span class="nx">v1</span><span class="mf">.6.0</span><span class="w"> </span><span class="c1">// UUID generation</span>
<span class="w"> </span><span class="nx">github</span><span class="p">.</span><span class="nx">com</span><span class="o">/</span><span class="nx">mattn</span><span class="o">/</span><span class="k">go</span><span class="o">-</span><span class="nx">sqlite3</span><span class="w"> </span><span class="nx">v1</span><span class="mf">.14.32</span><span class="w"> </span><span class="c1">// SQLite driver</span>
<span class="w"> </span><span class="nx">golang</span><span class="p">.</span><span class="nx">org</span><span class="o">/</span><span class="nx">x</span><span class="o">/</span><span class="nx">crypto</span><span class="w"> </span><span class="nx">v0</span><span class="mf">.45.0</span><span class="w"> </span><span class="c1">// Crypto utilities</span>
<span class="w"> </span><span class="nx">gopkg</span><span class="p">.</span><span class="nx">in</span><span class="o">/</span><span class="nx">yaml</span><span class="p">.</span><span class="nx">v3</span><span class="w"> </span><span class="nx">v3</span><span class="mf">.0.1</span><span class="w"> </span><span class="c1">// YAML parsing</span>
<span class="p">)</span>
</code></pre></div>
<h2 id="development-architecture">Development Architecture<a class="headerlink" href="#development-architecture" title="Permanent link">&para;</a></h2>
<h3 id="project-structure">Project Structure<a class="headerlink" href="#project-structure" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>fetch_ml/
├── cmd/ # CLI applications
│ ├── worker/ # ML worker service
│ ├── tui/ # Terminal UI
│ ├── data_manager/ # Data management
│ └── user_manager/ # User management
├── internal/ # Internal packages
│ ├── auth/ # Authentication system
│ ├── config/ # Configuration management
│ ├── container/ # Container operations
│ ├── database/ # Database operations
│ ├── logging/ # Logging utilities
│ ├── metrics/ # Metrics collection
│ └── network/ # Network utilities
├── configs/ # Configuration files
├── scripts/ # Setup and utility scripts
├── tests/ # Test suites
└── docs/ # Documentation
</code></pre></div>
<h3 id="package-dependencies">Package Dependencies<a class="headerlink" href="#package-dependencies" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Application Layer&quot;
Worker[cmd/worker]
TUI[cmd/tui]
DataMgr[cmd/data_manager]
UserMgr[cmd/user_manager]
end
subgraph &quot;Service Layer&quot;
Auth[internal/auth]
Config[internal/config]
Container[internal/container]
Database[internal/database]
end
subgraph &quot;Utility Layer&quot;
Logging[internal/logging]
Metrics[internal/metrics]
Network[internal/network]
end
Worker --&gt; Auth
Worker --&gt; Config
Worker --&gt; Container
TUI --&gt; Auth
DataMgr --&gt; Database
UserMgr --&gt; Auth
Auth --&gt; Logging
Container --&gt; Network
Database --&gt; Metrics
</code></pre></div>
<h2 id="monitoring-observability">Monitoring &amp; Observability<a class="headerlink" href="#monitoring-observability" title="Permanent link">&para;</a></h2>
<h3 id="metrics-collection">Metrics Collection<a class="headerlink" href="#metrics-collection" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Metrics Pipeline&quot;
App[Application] --&gt; Metrics[Metrics Collector]
Metrics --&gt; Export[Prometheus Exporter]
Export --&gt; Prometheus[Prometheus Server]
Prometheus --&gt; Grafana[Grafana Dashboard]
subgraph &quot;Metric Types&quot;
Counter[Counters]
Gauge[Gauges]
Histogram[Histograms]
Timer[Timers]
end
App --&gt; Counter
App --&gt; Gauge
App --&gt; Histogram
App --&gt; Timer
end
</code></pre></div>
<h3 id="logging-architecture">Logging Architecture<a class="headerlink" href="#logging-architecture" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Logging Pipeline&quot;
App[Application] --&gt; Logger[Structured Logger]
Logger --&gt; File[File Output]
Logger --&gt; Console[Console Output]
Logger --&gt; Syslog[Syslog Forwarder]
Syslog --&gt; Aggregator[Log Aggregator]
Aggregator --&gt; Storage[Log Storage]
Storage --&gt; Viewer[Log Viewer]
end
</code></pre></div>
<h2 id="deployment-architecture">Deployment Architecture<a class="headerlink" href="#deployment-architecture" title="Permanent link">&para;</a></h2>
<h3 id="container-deployment">Container Deployment<a class="headerlink" href="#container-deployment" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Deployment Stack&quot;
Image[Container Image]
Registry[Container Registry]
Orchestrator[Docker Compose]
Config[ConfigMaps/Secrets]
Storage[Persistent Storage]
Image --&gt; Registry
Registry --&gt; Orchestrator
Config --&gt; Orchestrator
Storage --&gt; Orchestrator
end
</code></pre></div>
<h3 id="service-discovery">Service Discovery<a class="headerlink" href="#service-discovery" title="Permanent link">&para;</a></h3>
<div class="highlight"><pre><span></span><code>graph TB
subgraph &quot;Service Mesh&quot;
Gateway[API Gateway]
Discovery[Service Discovery]
Worker[Worker Service]
Data[Data Service]
Redis[Redis Cluster]
Gateway --&gt; Discovery
Discovery --&gt; Worker
Discovery --&gt; Data
Discovery --&gt; Redis
end
</code></pre></div>
<h2 id="future-architecture-considerations">Future Architecture Considerations<a class="headerlink" href="#future-architecture-considerations" title="Permanent link">&para;</a></h2>
<h3 id="microservices-evolution">Microservices Evolution<a class="headerlink" href="#microservices-evolution" title="Permanent link">&para;</a></h3>
<ul>
<li><strong>API Gateway</strong>: Centralized routing and authentication</li>
<li><strong>Service Mesh</strong>: Inter-service communication</li>
<li><strong>Event Streaming</strong>: Kafka for job events</li>
<li><strong>Distributed Tracing</strong>: OpenTelemetry integration</li>
<li><strong>Multi-tenant</strong>: Tenant isolation and quotas</li>
</ul>
<h3 id="homelab-features">Homelab Features<a class="headerlink" href="#homelab-features" title="Permanent link">&para;</a></h3>
<ul>
<li><strong>Docker Compose</strong>: Simple container orchestration</li>
<li><strong>Local Development</strong>: Easy setup and testing</li>
<li><strong>Security</strong>: Built-in authentication and encryption</li>
<li><strong>Monitoring</strong>: Basic health checks and logging</li>
</ul>
<hr />
<p>This architecture provides a solid foundation for secure, scalable machine learning experiments while maintaining simplicity and developer productivity.</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.instant", "navigation.tracking", "navigation.tabs", "navigation.sections", "navigation.expand", "navigation.indexes", "toc.integrate", "search.highlight", "search.share"], "search": "../assets/javascripts/workers/search.7a47a382.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.e71a0d61.min.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink