Smarter Architecture

Smarter is a Django application, built in four layers. Each layer depends only on the layers below it: Smarter’s Django apps use Smarter’s own subsystems, which extend a handful of third-party Django apps, which run on Linux.

┌──────────────────────────────────────────────────────────────────────────────────────┐
│  CLIENTS     smarter CLI  ·  REST /api/v1/cli/<cmd>/  ·  Web console (React apps)    │
│              ·  deployed LLMClient hosts (django-hosts subdomains)                   │
└───────────────────────────────────────────┬──────────────────────────────────────────┘
                                            │  HTTP
┌───────────────────────────────────────────▼──────────────────────────────────────────┐
│ 4. SMARTER DJANGO APPS                           smarter/smarter/apps/<app>          │
│                                                                                      │
│  ┌─ Platform ──────────┐ ┌─ LLM runtime ───────────┐ ┌─ Tools & context ──────────┐  │
│  │ account             │ │ llmclient (+Custom Dom.)│ │ llmtool    (plugins)       │  │
│  │ api      (v1, cli)  │ │ llmhost                 │ │ connection (sql / api)     │  │
│  │ dashboard (console) │ │ provider                │ │ mcpclient · mcpserver      │  │
│  │ docs                │ │ prompt                  │ │ vectorstore · vectorsearch │  │
│  │ secret              │ │ orchestrator            │ │ guardrail                  │  │
│  └─────────────────────┘ │ proxy                   │ └────────────────────────────┘  │
│                          └─────────────────────────┘                                 │
│  ┌─ infrastructure ──────── facade: .dns .certificates .kubernetes .email ────────┐  │
│  │   providers: AWS (Route53, ACM, EKS) · in-memory fake (tests)                  │  │
│  └────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────┬──────────────────────────────────────────┘
┌───────────────────────────────────────────▼──────────────────────────────────────────┐
│ 3. SMARTER SUBSYSTEMS                                 smarter/smarter/lib/*          │
│                                                                                      │
│ ┌─ SAM ─────────────────┐ ┌─ caching ──────┐ ┌─ logging ─────────┐ ┌─ journal ─────┐ │
│ │ lib/manifest          │ │ lib/cache      │ │ lib/logging       │ │ lib/journal   │ │
│ │ YAML manifest         │ │ Redis-backed   │ │ per-request log   │ │ (Django app)  │ │
│ │  → loader             │ │ cache helpers  │ │ context           │ │ records every │ │
│ │  → Pydantic models    │ │ & decorators   │ │ middleware,       │ │ API/CLI       │ │
│ │  → controller         │ │                │ │ waffle-switched   │ │ request and   │ │
│ │  → AbstractBroker     │ │                │ │ loggers           │ │ response      │ │
│ │  (apply/get/describe/ │ │                │ │                   │ │               │ │
│ │   delete/deploy)      │ │                │ │                   │ │               │ │
│ └───────────────────────┘ └────────────────┘ └───────────────────┘ └───────────────┘ │
│ supporting: lib/drf (Smarter auth tokens, token middleware) · lib/django (base       │
│   models, views, middleware, waffle) · lib/celery_conf · lib/unittest · lib/typing   │
└───────────────────────────────────────────┬──────────────────────────────────────────┘
┌───────────────────────────────────────────▼──────────────────────────────────────────┐
│ 2. THIRD-PARTY DJANGO APPS AND FRAMEWORKS                                            │
│                                                                                      │
│ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐│
│ │ DRF           │ │ knox         │ │ taggit      │ │ waffle       │ │ Celery        ││
│ │ REST views,   │ │ API-key      │ │ resource    │ │ feature      │ │ async tasks,  ││
│ │ serializers   │ │ token auth   │ │ tags        │ │ flags and    │ │ beat (redbeat,││
│ │ (+ drf_yasg)  │ │              │ │             │ │ switches     │ │ django_celery_││
│ └───────────────┘ └──────────────┘ └─────────────┘ └──────────────┘ │ beat)         ││
│                                                                     └───────────────┘│
│ also: django_hosts · corsheaders · social_django · storages · Pydantic               │
│                                                                                      │
│ Django  (admin, auth, contenttypes, sessions, messages, staticfiles, ...)            │
└───────────────────────────────────────────┬──────────────────────────────────────────┘
┌───────────────────────────────────────────▼──────────────────────────────────────────┐
│ 1. LINUX RUNTIME                                                                     │
│                                                                                      │
│  Debian (python slim) container image  ·  kubectl                                    │
│  ┌──────────────┐ ┌──────────────┐ ┌───────────────────────────┐ ┌──────────────────┐│
│  │ smarter-app  │ │ smarter-beat │ │ smarter-worker            │ │ smarter-mariadb  ││
│  │ (Django)     │ │ (Celery beat)│ │ smarter-worker-infra      │ │ smarter-redis    ││
│  └──────────────┘ └──────────────┘ └───────────────────────────┘ └──────────────────┘│
│  Production: Kubernetes (AWS EKS)                                                    │
└──────────────────────────────────────────────────────────────────────────────────────┘

Linux

Smarter ships as a single Docker image, built on the official Debian-based Python slim image, with kubectl added so that the platform can manage the Kubernetes resources of deployed applications. The same image runs as the Django application server (smarter-app), the Celery workers (smarter-worker and smarter-worker-infrastructure) and the Celery beat scheduler (smarter-beat). MariaDB holds the data and Redis serves as both the cache and the Celery message broker. In production all of these run on Kubernetes. See Docker and Smarter on Kubernetes.

Third-Party Django Apps

Smarter builds on Django and a short list of well-established third-party apps:

  • Django REST Framework (DRF) provides the views and serializers of the Smarter API.

  • knox provides the token authentication behind Smarter API keys.

  • taggit lets every resource carry tags.

  • waffle provides feature flags and switches, which also turn individual loggers on and off.

  • Celery runs long or periodic work, such as deploying an LLMClient or issuing a certificate, outside the request cycle.

Smarter Subsystems

The smarter.lib package holds the framework code that the Django apps share. Four subsystems shape nearly every request:

  • SAM, the Smarter Application Manifest. Every resource is declared in a YAML manifest that a loader validates against Pydantic models and hands to a broker, which implements the apply, get, describe, delete and deploy commands for that kind of resource.

  • Caching wraps Django’s Redis cache with Smarter’s own helpers and decorators. See Smarter Caching.

  • Logging adds per-request context, such as the user, to every log line, and lets each logger be switched on with waffle. See Smarter Logging.

  • The journal records every API and CLI request with its response, giving an audit trail of who changed what. See Smarter Journal.

Smarter Django Apps

Each family of resources is a Django app in smarter.apps, with its models, its SAM broker, its API views and its web console pages. The apps fall into three groups:

The infrastructure app is the only part of Smarter that talks to the cloud. It offers a single facade for DNS, TLS certificates, Kubernetes and email, with an AWS provider for production and an in-memory provider for tests. See Infrastructure Services.