Add architecture document and RT analysis reference
This commit is contained in:
Gjermund Høsøien Wiggen
310
docs/architecture.md
Normal file
310
docs/architecture.md
Normal file
@@ -0,0 +1,310 @@
|
|||||||
|
# Tessera Architecture
|
||||||
|
|
||||||
|
## Principle
|
||||||
|
|
||||||
|
Tessera is RT's paradigm rebuilt: a ticketing system that makes zero assumptions about your workflow. It provides composable primitives — scrips, custom fields, lifecycles, transactions — and you build your process on top.
|
||||||
|
|
||||||
|
Everything is a transaction. Everything is queryable. Everything is automatable.
|
||||||
|
|
||||||
|
## Philosophy
|
||||||
|
|
||||||
|
- **Config > Code**: Scrips are defined in a web UI, not in source files. The scrip runtime is sandboxed, the conditions and actions are configurable from data.
|
||||||
|
- **Prepare/Commit**: Every state change goes through a two-phase dispatch that can be dry-run. No action executes without the user knowing what will happen.
|
||||||
|
- **SystemUser**: Automation runs elevated. The system acts on behalf of the configuration, not the triggering user's permissions.
|
||||||
|
- **Single Binary**: The core (Rust) ships as one binary. Integration plugins (Go) are sidecar processes over gRPC.
|
||||||
|
- **PostgreSQL**: No ORM. Raw SQL with compile-time query building. Query builder compiles to SQL, not to an ORM abstraction.
|
||||||
|
|
||||||
|
## MVP Scope — "ScripFoundry"
|
||||||
|
|
||||||
|
The MVP is the scrip runtime + enough scaffolding to exercise it. This is the wedge: nobody else has a configurable event-driven automation engine with prepare/commit and a web UI for defining rules.
|
||||||
|
|
||||||
|
### What's In
|
||||||
|
|
||||||
|
1. **Ticket model** — id, subject, queue_id, status, owner_id, creator_id, created_at, updated_at
|
||||||
|
2. **Queue model** — id, name, description, lifecycle_id
|
||||||
|
3. **Transaction model** — id, ticket_id, transaction_type, field, old_value, new_value, creator_id, created_at
|
||||||
|
4. **Lifecycle state machine** — per-queue status definitions, transitions, transition-gating rights. Hardcoded "default" lifecycle for MVP.
|
||||||
|
5. **Scrip engine** (the crown jewel):
|
||||||
|
- Define conditions (OnCreate, OnStatusChange, OnResolve, UserDefined)
|
||||||
|
- Define actions (SendEmail, SetCustomField, Webhook)
|
||||||
|
- Define templates (variable substitution: `{$ticket.id}`, `{$ticket.subject}`, etc.)
|
||||||
|
- Prepare/Commit dispatch with sort ordering
|
||||||
|
- TransactionCreate and TransactionBatch stages
|
||||||
|
- Dry-run mode: /api/tickets/:id/preview returns "what will happen if I apply this update"
|
||||||
|
6. **Custom Fields (MVP subset)**:
|
||||||
|
- Freeform text, Select single, Select multiple
|
||||||
|
- Attached to tickets
|
||||||
|
- Queryable
|
||||||
|
- Appear in variable substitution
|
||||||
|
7. **REST API** — CRUD for tickets, queues, transactions, scrips, custom fields. The UI is a separate concern.
|
||||||
|
8. **Email actions** — SMTP send via scrip action. Template-driven subject/body.
|
||||||
|
9. **Webhook actions** — HTTP POST on scrip trigger. Template-driven URL/body/headers.
|
||||||
|
|
||||||
|
### What's Out (Post-MVP)
|
||||||
|
|
||||||
|
- User management (hardcode admin user)
|
||||||
|
- Authentication/authorization (trust boundary not in MVP)
|
||||||
|
- Full ACL system
|
||||||
|
- Transaction query builder UI (API-only)
|
||||||
|
- Multi-tenancy
|
||||||
|
- Migration/import tools
|
||||||
|
- Attachments
|
||||||
|
- Real email ingestion (only outbound for MVP)
|
||||||
|
- Notifications beyond email and webhooks (no Slack, SMS, etc.)
|
||||||
|
- Admin web UI (API-driven, build later)
|
||||||
|
- Custom scrip code execution (UserDefined is config-based, not code-based in MVP)
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Component Diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ tessera-core (Rust) │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||||||
|
│ │ HTTP API │ │ Scrip │ │ Lifecycle │ │
|
||||||
|
│ │ (axum) │ │ Engine │ │ State Machine │ │
|
||||||
|
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ ┌────┴────────────┴───────────────┴──────────┐ │
|
||||||
|
│ │ Query Builder │ │
|
||||||
|
│ │ (SQL generation from typed filter ASTs) │ │
|
||||||
|
│ └────────────────────┬───────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌────────────────────┴───────────────────────┐ │
|
||||||
|
│ │ PostgreSQL (sqlx) │ │
|
||||||
|
│ └────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌────────────────────────────────────────────┐ │
|
||||||
|
│ │ gRPC Server (tonic) │ │
|
||||||
|
│ └────────────────┬───────────────────────────┘ │
|
||||||
|
└───────────────────┼────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────┼───────────┐
|
||||||
|
│ │ │
|
||||||
|
┌───────┴───┐ ┌─────┴─────┐ ┌──┴──────────┐
|
||||||
|
│ Email │ │ Webhook │ │ Custom ... │
|
||||||
|
│ Connector│ │ Connector│ │ Connectors │
|
||||||
|
│ (Go) │ │ (Go) │ │ (Go) │
|
||||||
|
└───────────┘ └───────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Technology Decisions
|
||||||
|
|
||||||
|
| Layer | Technology | Rationale |
|
||||||
|
|-------|-----------|-----------|
|
||||||
|
| HTTP framework | axum | Ergonomic, tower-based middleware, best-in-class Rust HTTP |
|
||||||
|
| Database | PostgreSQL 15+ | Transactional DDL, CTEs, JSONB, full-text search |
|
||||||
|
| SQL driver | sqlx | Compile-time checked queries, async, migrations |
|
||||||
|
| gRPC | tonic/prost | Well-typed contracts between Rust core and Go integrations |
|
||||||
|
| Scrip sandbox | wasmtime | Execute user-defined scrip conditions/actions in WASM sandbox |
|
||||||
|
| Templating | Tera | Django-like syntax, variable interpolation |
|
||||||
|
| Serialization | serde + serde_json | Standard |
|
||||||
|
| Logging | tracing | Structured, async-aware |
|
||||||
|
| Config | figment | Hierarchical config (file + env + defaults) |
|
||||||
|
| Integration runtime | Go 1.22+ | Single binary, excellent gRPC support, ops ecosystem |
|
||||||
|
|
||||||
|
### Data Model (Core Tables)
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Tickets
|
||||||
|
CREATE TABLE tickets (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
subject TEXT NOT NULL,
|
||||||
|
queue_id UUID NOT NULL REFERENCES queues(id),
|
||||||
|
status TEXT NOT NULL,
|
||||||
|
owner_id UUID REFERENCES users(id),
|
||||||
|
creator_id UUID NOT NULL REFERENCES users(id),
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
started_at TIMESTAMPTZ,
|
||||||
|
resolved_at TIMESTAMPTZ
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Queues
|
||||||
|
CREATE TABLE queues (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL UNIQUE,
|
||||||
|
description TEXT,
|
||||||
|
lifecycle_id UUID REFERENCES lifecycles(id),
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Lifecycles
|
||||||
|
CREATE TABLE lifecycles (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL UNIQUE,
|
||||||
|
definition JSONB NOT NULL,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Transactions (the universal event log)
|
||||||
|
CREATE TABLE transactions (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
ticket_id UUID NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
|
||||||
|
transaction_type TEXT NOT NULL, -- 'Create', 'StatusChange', 'Correspond', 'Comment', 'CustomField', 'EmailRecord', etc.
|
||||||
|
field TEXT,
|
||||||
|
old_value TEXT,
|
||||||
|
new_value TEXT,
|
||||||
|
data JSONB,
|
||||||
|
creator_id UUID NOT NULL REFERENCES users(id),
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Scrips
|
||||||
|
CREATE TABLE scrips (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
queue_id UUID REFERENCES queues(id), -- NULL = global
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
condition_type TEXT NOT NULL, -- 'OnCreate', 'OnStatusChange', etc.
|
||||||
|
condition_config JSONB NOT NULL DEFAULT '{}',
|
||||||
|
action_type TEXT NOT NULL, -- 'SendEmail', 'SetCustomField', 'Webhook'
|
||||||
|
action_config JSONB NOT NULL DEFAULT '{}',
|
||||||
|
template_id UUID REFERENCES templates(id),
|
||||||
|
stage TEXT NOT NULL DEFAULT 'TransactionCreate', -- 'TransactionCreate' or 'TransactionBatch'
|
||||||
|
sort_order INT NOT NULL DEFAULT 0,
|
||||||
|
disabled BOOLEAN NOT NULL DEFAULT false,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Templates
|
||||||
|
CREATE TABLE templates (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
queue_id UUID REFERENCES queues(id), -- NULL = global
|
||||||
|
subject_template TEXT NOT NULL,
|
||||||
|
body_template TEXT NOT NULL,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
UNIQUE(name, queue_id)
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Custom Fields
|
||||||
|
CREATE TABLE custom_fields (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
field_type TEXT NOT NULL, -- 'Freeform', 'SelectSingle', 'SelectMulti'
|
||||||
|
values JSONB, -- For select types: ["opt1", "opt2"]
|
||||||
|
max_values INT NOT NULL DEFAULT 1, -- 0 = unlimited
|
||||||
|
pattern TEXT, -- Validation regex
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Custom Field <-> Queue attachment
|
||||||
|
CREATE TABLE queue_custom_fields (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
queue_id UUID REFERENCES queues(id),
|
||||||
|
custom_field_id UUID REFERENCES custom_fields(id) ON DELETE CASCADE,
|
||||||
|
sort_order INT NOT NULL DEFAULT 0,
|
||||||
|
UNIQUE(queue_id, custom_field_id)
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Custom Field Values (on tickets)
|
||||||
|
CREATE TABLE custom_field_values (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
custom_field_id UUID NOT NULL REFERENCES custom_fields(id) ON DELETE CASCADE,
|
||||||
|
ticket_id UUID NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
|
||||||
|
value TEXT NOT NULL,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
UNIQUE(custom_field_id, ticket_id, value)
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Users (MVP: minimal)
|
||||||
|
CREATE TABLE users (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
username TEXT NOT NULL UNIQUE,
|
||||||
|
email TEXT,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Design (MVP Endpoints)
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/health
|
||||||
|
GET /api/tickets
|
||||||
|
POST /api/tickets
|
||||||
|
GET /api/tickets/:id
|
||||||
|
PATCH /api/tickets/:id
|
||||||
|
POST /api/tickets/:id/preview -- Dry-run: returns scrips that would fire
|
||||||
|
GET /api/tickets/:id/transactions
|
||||||
|
POST /api/tickets/:id/comment -- Add comment (creates transaction)
|
||||||
|
GET /api/queues
|
||||||
|
POST /api/queues
|
||||||
|
GET /api/scrips
|
||||||
|
POST /api/scrips
|
||||||
|
GET /api/scrips/:id
|
||||||
|
PATCH /api/scrips/:id
|
||||||
|
GET /api/custom-fields
|
||||||
|
POST /api/custom-fields
|
||||||
|
GET /api/lifecycles
|
||||||
|
POST /api/lifecycles
|
||||||
|
POST /api/tickets/search -- TicketSQL query body
|
||||||
|
```
|
||||||
|
|
||||||
|
### Scrip Engine Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Ticket update request arrives → axum handler
|
||||||
|
2. Validate transition (lifecycle state machine)
|
||||||
|
3. Apply update → creates Transaction record(s)
|
||||||
|
4. Scrip Engine triggered:
|
||||||
|
a. Load matching scrips (global + queue-specific)
|
||||||
|
b. Filter by ApplicableTransTypes matching transaction type
|
||||||
|
c. Sort by sort_order
|
||||||
|
d. PREPARE PHASE: For each scrip:
|
||||||
|
- Evaluate condition (no side effects)
|
||||||
|
- If condition matches, build action payload with template substitution
|
||||||
|
- Push to prepared_scrips
|
||||||
|
e. COMMIT PHASE: For each prepared scrip:
|
||||||
|
- Execute action (send email, fire webhook, set CF, etc.)
|
||||||
|
- Create EmailRecord or WebhookDelivery transaction on success
|
||||||
|
5. Return response: { ticket, transactions, scrips_fired: [...] }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
tessera/
|
||||||
|
├── Cargo.toml
|
||||||
|
├── README.md
|
||||||
|
├── docs/
|
||||||
|
│ ├── architecture.md (this file)
|
||||||
|
│ └── rt-analysis.md (RT deep-dive reference)
|
||||||
|
├── crates/
|
||||||
|
│ ├── tessera-core/ Main library: models, scrip engine, lifecycle
|
||||||
|
│ │ ├── Cargo.toml
|
||||||
|
│ │ └── src/
|
||||||
|
│ │ ├── lib.rs
|
||||||
|
│ │ ├── models/ ticket, queue, transaction, scrip, etc.
|
||||||
|
│ │ ├── scrip/ engine, conditions, actions, templates
|
||||||
|
│ │ ├── lifecycle/ state machine, transition validation
|
||||||
|
│ │ ├── query/ query builder, TicketSQL AST
|
||||||
|
│ │ └── db/ sqlx queries, migrations
|
||||||
|
│ ├── tessera-api/ HTTP API server (axum)
|
||||||
|
│ │ ├── Cargo.toml
|
||||||
|
│ │ └── src/
|
||||||
|
│ │ ├── main.rs
|
||||||
|
│ │ ├── routes/ ticket, queue, scrip, lifecycle, search
|
||||||
|
│ │ └── middleware/ logging, error handling
|
||||||
|
│ └── tessera-grpc/ gRPC server for integration connectors
|
||||||
|
│ ├── Cargo.toml
|
||||||
|
│ └── src/
|
||||||
|
├── proto/ Protobuf definitions
|
||||||
|
│ └── tessera/
|
||||||
|
│ └── v1/
|
||||||
|
│ ├── tickets.proto
|
||||||
|
│ ├── scrips.proto
|
||||||
|
│ └── actions.proto
|
||||||
|
├── integrations/ Go integration connectors
|
||||||
|
│ ├── go.mod
|
||||||
|
│ ├── cmd/
|
||||||
|
│ │ ├── email-connector/
|
||||||
|
│ │ └── webhook-connector/
|
||||||
|
│ └── pkg/
|
||||||
|
│ └── tessera/ Generated gRPC client
|
||||||
|
├── migrations/ SQLx migrations
|
||||||
|
└── scripts/ Dev tooling
|
||||||
|
└── dev-setup.sh
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user