Skip to main content

​
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 full-text search (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 — Relational database for persistent storage
  • 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:
NetworkPurposeAccess
edgePublic-facing servicesInternet via Traefik
internalService-to-service communicationAPI, AI, Knowledge, databases
agent_internalAgent container isolationAgentbox → 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 TypeUsed ForHow It Works
HTTP-01Public services (API, MCP Gateway, UI, etc.)Let’s Encrypt validates via port 80
DNS-01VPN-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.

​
Next Steps

Services

Detailed breakdown of each service and its responsibilities.

API Reference

Explore the REST API endpoints.