Architecture

Dependency graph

Every capability builds on a shared foundation, which provides common models, settings, and logging. Services do not depend on each other — they communicate over HTTP if needed.

Core Foundation
  ├── Triage
  ├── Reply
  ├── QA
  ├── Sentiment
  ├── Pulse
  ├── KB
  ├── Macro
  ├── Data
  └── Template

Services working together

While each service is independent, they form a powerful pipeline when combined:

Ticket arrives → Triage (classify + route)
                  ↓
                Agent receives pre-classified ticket
                  ↓
                Reply (generates draft response)  ←  KB (semantic search for grounding)
                  ↓
                Sentiment (monitors each message in parallel)
                  ↓
                After resolution → QA (scores conversation quality)
                                 → Pulse (aggregates operational metrics)

See The Ticket Lifecycle for a detailed walkthrough with code examples.

Shared domain models

All services share the same domain language through the core library's Pydantic models:

Model	Purpose
`Ticket`	Support ticket with subject, status, priority, channel, tags
`Customer`	Customer profile with name, email, tier, metadata
`Agent`	Support agent with teams, skills, active status
`Message`	Single message with author type, body, channel
`Conversation`	Thread of messages linked to a ticket

Key enums:

Enum	Values
`Priority`	`low`, `medium`, `high`, `urgent`
`TicketStatus`	`new`, `open`, `pending`, `solved`, `closed`
`Channel`	`email`, `chat`, `phone`, `social`, `web`
`CustomerTier`	`free`, `basic`, `premium`, `enterprise`
`AuthorType`	`customer`, `agent`, `system`

Shared settings

Every service subclasses SimpliSettings from the core library, which provides:

Field	Default	Env var
`app_env`	`development`	`APP_ENV`
`app_host`	`0.0.0.0`	`APP_HOST`
`app_port`	`8000`	`APP_PORT`
`app_log_level`	`info`	`APP_LOG_LEVEL`
`app_debug`	`false`	`APP_DEBUG`

Services add their own fields on top. Settings are automatically loaded from environment variables and .env files.

Shared logging

All services use setup_logging() from the core library, which configures structlog with:

Console rendering in development, JSON in production
Configurable log level
Context variable support for request tracing

Service structure

Every service follows the same layout:

src/<package>/
  __init__.py     # Package version
  app.py          # FastAPI application, models, endpoints
  settings.py     # Settings(SimpliSettings) subclass
  cli.py          # Typer CLI with `serve` and `version` commands
tests/
  test_app.py     # API endpoint tests
  conftest.py     # Shared fixtures

Each service:

Exposes a REST API via FastAPI
Has a CLI to start the server (simpli-<name> serve)
Provides a /health endpoint
Uses structlog for structured logging
Reads configuration from environment variables / .env files