Architecture Overview

Hill90 is a Docker-based microservices platform hosted on a single VPS running AlmaLinux.

System Layers

The platform is organized into four layers:

Edge Layer

Traefik serves as the reverse proxy and load balancer, providing:

Automatic HTTPS via Let’s Encrypt
HTTP-01 challenges for public services
DNS-01 challenges for VPN-only services
Routing, middleware, and rate limiting

Application Layer

Application services handle business logic:

API — REST API gateway (Express/TypeScript) for agent management, model policies, and user profiles
AI (Model-Router) — Internal policy-gated LLM inference gateway (FastAPI/Python)
Knowledge (AKM) — Persistent agent memory with hybrid search (FTS + pgvector semantic, FastAPI/Python)
MCP — Model Context Protocol gateway (FastAPI/Python), JWT-authenticated
Agentbox — Sandboxed agent runtime containers (Python, Starlette/uvicorn)
Keycloak — Identity provider (OIDC/OAuth2) at auth.hill90.com
UI — Next.js frontend application

Data Layer

PostgreSQL + pgvector — Relational database with vector similarity search for semantic embeddings
MinIO — S3-compatible object storage for files and avatars
OpenBao — Secrets management (vault-first with encrypted backup)

Observability Layer

A full LGTM stack provides monitoring, logging, and tracing:

Prometheus — Metrics collection and alerting
Grafana — Dashboards and exploration
Loki — Log aggregation
Tempo — Distributed tracing
OpenTelemetry — Application tracing instrumentation
Collectors: Promtail, Node Exporter, cAdvisor, postgres-exporter

Network Architecture

Internet
   |
Traefik (edge network)
   |
   +-- Public Services (HTTP-01 certs)
   |     API, MCP Gateway, Keycloak, UI
   |
   +-- Internal Services
   |     AI (Model-Router), Knowledge (AKM), PostgreSQL, MinIO
   |
   +-- Agent Network
   |     Agentbox → AI Service, Knowledge Service
   |
   +-- Observability
         Prometheus, Loki, Tempo, Grafana

Network isolation is enforced through Docker networks:

Network	Purpose	Access
`edge`	Public-facing services	Internet via Traefik
`internal`	Service-to-service communication	API, AI, Knowledge, databases
`agent_internal`	Agent container isolation	Agentbox → AI + Knowledge only

VPN-only services (Traefik dashboard, Grafana, MinIO console) are protected by IP whitelist middleware, accessible only through the VPN network. The AI service and Knowledge service are internal-only — they are not publicly routed through Traefik.

Certificate Management

Challenge Type	Used For	How It Works
HTTP-01	Public services (API, MCP Gateway, UI, etc.)	Let’s Encrypt validates via port 80
DNS-01	VPN-only services (Traefik dashboard, Grafana)	DNS TXT record validation via DNS Manager webhook

The DNS Manager is an internal webhook that translates Traefik ACME requests into DNS API calls for TXT record management.

Deployment Model

VPS provisioning — Automated via infrastructure APIs
Configuration — Ansible playbooks for OS bootstrap
Container orchestration — Docker Compose per service group
CI/CD — GitHub Actions with path-filtered triggers
DNS management — Automated via DNS API

Each service group has its own Docker Compose file and deploy target, enabling independent deployment and rollback.

Getting Started

Features

Architecture

API Reference

Architecture Overview

Architecture Overview

System Layers

Edge Layer

Application Layer

Data Layer

Observability Layer

Network Architecture

Certificate Management

Deployment Model

Next Steps

Services

API Reference

​Architecture Overview

​System Layers

​Edge Layer

​Application Layer

​Data Layer

​Observability Layer

​Network Architecture

​Certificate Management

​Deployment Model

​Next Steps

Services

API Reference

Architecture Overview

System Layers

Edge Layer

Application Layer

Data Layer

Observability Layer

Network Architecture

Certificate Management

Deployment Model

Next Steps