papers/hanzo-platform/sections/02-architecture.tex

\section{Architecture}

\label{sec:architecture}

\subsection{System Overview}

Hanzo Platform is built on Kubernetes with custom operators for AI workload management:

\begin{enumerate}[leftmargin=1.4em]
    \item \textbf{Control Plane}: API server, scheduler, build system, and resource manager.
    \item \textbf{Compute Plane}: Kubernetes clusters with GPU and CPU node pools.
    \item \textbf{Data Plane}: Managed PostgreSQL, Redis, vector databases, and object storage.
    \item \textbf{Network Plane}: Ingress controllers with WebSocket support, CDN, and DNS management.
    \item \textbf{Observability Plane}: Metrics, logging, tracing, and cost analytics.
\end{enumerate}

\subsection{Application Model}

\begin{definition}[Hanzo Application]
An application is a tuple $A = (S, R, C, E)$ where:
\begin{itemize}[leftmargin=1.1em]
    \item $S$: Source specification (Git repository, Docker image, or Nixpack).
    \item $R$: Resource requirements (compute, storage, AI services).
    \item $C$: Configuration (environment variables, secrets, domains).
    \item $E$: Scaling policy (min/max replicas, autoscaler parameters).
\end{itemize}
\end{definition}

Applications are defined declaratively in a \texttt{hanzo.yaml} file:

\begin{lstlisting}[language=yaml,caption={Example hanzo.yaml for an AI application.}]
name: my-rag-app
runtime: python-3.12

services:
  web:
    build: .
    port: 8000
    gpu: a10g
    replicas: {min: 1, max: 8}
    scaling:
      metric: tokens_per_second
      target: 1000

resources:
  llm:
    provider: hanzo-gateway
    models: [claude-3.5-sonnet, gpt-4o]
    budget: $500/month
  vector:
    engine: pgvector
    dimensions: 1024
    storage: 50GB
  db:
    engine: postgres
    storage: 20GB
  cache:
    engine: redis
    memory: 2GB
\end{lstlisting}