# brawliot/abs architecture

> Architecture diagram of the GitHub repository brawliot/abs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brawliot/abs
- Repository: https://github.com/brawliot/abs

## Overview

This repository implements a business-transaction workflow platform: users submit actions through a web UI, text may be interpreted into an intent, policies judge whether a lifecycle transition is allowed, and the runtime records events from which state is derived. Around that core are business archetypes, rule/fact evaluation, process generation and diagnosis, presentation, and tenant-aware hosting. The README is empty; connections below are limited to source excerpts and SOURCE INDEX references, so unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`web/action-handler.ts`](https://github.com/brawliot/abs/blob/main/web/action-handler.ts) (Action handler), [`core/derivation.ts`](https://github.com/brawliot/abs/blob/main/core/derivation.ts) (State derivation), [`archetypes/catalog.ts`](https://github.com/brawliot/abs/blob/main/archetypes/catalog.ts) (Archetype catalog), [`web/server.ts`](https://github.com/brawliot/abs/blob/main/web/server.ts) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_http["HTTP server<br/>[server.ts]"]
  node_action["Action handler<br/>[action-handler.ts]"]
  node_interpreter["Intent interpreter<br/>[interpret.ts]"]
  node_presentation["UI rendering<br/>[render-app.ts]"]
end

subgraph group_domain["Transaction model"]
  node_archetypes["Archetype catalog<br/>[catalog.ts]"]
  node_composition["Archetype composition<br/>[composition.ts]"]
  node_lifecycle["Lifecycle model<br/>[lifecycle.ts]"]
  node_elements["Domain elements<br/>[subtypes.ts]"]
  node_derivation["State derivation<br/>[derivation.ts]"]
  node_events["Domain events<br/>[events.ts]"]
end

subgraph group_evaluation["Rules and facts"]
  node_judge["Policy judge<br/>[judge.ts]"]
  node_facts["Fact provider<br/>[provider.ts]"]
end

subgraph group_product["Configuration and insight"]
  node_composer["Process composer<br/>[compose.ts]"]
  node_generator["Process generator<br/>[generate.ts]"]
  node_diagnosis["Business diagnosis<br/>[engine.ts]"]
  node_presenter["Insight presenter<br/>[present.ts]"]
end

subgraph group_platform["Runtime platform"]
  node_eventstore[("Event store<br/>[event-store.ts]")]
  node_llm["LLM client<br/>[client.ts]"]
  node_identity[("Identity and tenancy<br/>[identity.ts]")]
  node_hosting["Tenant routing<br/>[pool-router.ts]"]
end

node_user(("User"))

node_user -->|"submits actions"| node_http
node_http -->|"routes actions"| node_action
node_http -->|"renders views"| node_presentation
node_action -->|"interprets input"| node_interpreter
node_action -->|"requests judgment"| node_judge
node_action -->|"derives current state"| node_derivation
node_action -->|"checks composition blocks"| node_composition
node_action -->|"reads event history"| node_eventstore
node_action -->|"uses transition events"| node_events
node_archetypes -->|"supplies definitions"| node_composition
node_archetypes -->|"defines workflows"| node_lifecycle
node_archetypes -->|"uses element types"| node_elements
node_derivation -->|"derives from lifecycle"| node_lifecycle
node_derivation -->|"derives from events"| node_events
node_judge -->|"checks transition"| node_derivation
node_judge -->|"evaluates fact rules"| node_facts
node_hosting -->|"configures tenant store"| node_eventstore
node_hosting -->|"configures identity store"| node_identity
node_diagnosis -->|"uses archetype composition"| node_composition
node_generator -.->|"supports process analysis"| node_diagnosis
node_composer -.->|"produces process input"| node_generator
node_presenter -.->|"feeds user-facing insight"| node_presentation
node_interpreter -->|"extracts with LLM"| node_llm

click node_http "https://github.com/brawliot/abs/blob/main/web/server.ts"
click node_action "https://github.com/brawliot/abs/blob/main/web/action-handler.ts"
click node_interpreter "https://github.com/brawliot/abs/blob/main/interpreter/interpret.ts"
click node_presentation "https://github.com/brawliot/abs/blob/main/web/render-app.ts"
click node_archetypes "https://github.com/brawliot/abs/blob/main/archetypes/catalog.ts"
click node_composition "https://github.com/brawliot/abs/blob/main/archetypes/composition.ts"
click node_lifecycle "https://github.com/brawliot/abs/blob/main/core/lifecycle.ts"
click node_elements "https://github.com/brawliot/abs/blob/main/elements/subtypes.ts"
click node_derivation "https://github.com/brawliot/abs/blob/main/core/derivation.ts"
click node_events "https://github.com/brawliot/abs/blob/main/core/events.ts"
click node_eventstore "https://github.com/brawliot/abs/blob/main/core/event-store.ts"
click node_judge "https://github.com/brawliot/abs/blob/main/policies/judge.ts"
click node_facts "https://github.com/brawliot/abs/blob/main/facts/provider.ts"
click node_composer "https://github.com/brawliot/abs/blob/main/composer/compose.ts"
click node_generator "https://github.com/brawliot/abs/blob/main/generator/generate.ts"
click node_diagnosis "https://github.com/brawliot/abs/blob/main/diagnosis/engine.ts"
click node_presenter "https://github.com/brawliot/abs/blob/main/presenter/present.ts"
click node_llm "https://github.com/brawliot/abs/blob/main/llm/client.ts"
click node_identity "https://github.com/brawliot/abs/blob/main/policies/identity.ts"
click node_hosting "https://github.com/brawliot/abs/blob/main/hosting/pool-router.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http,node_action,node_interpreter,node_presentation,node_user toneBlue
class node_archetypes,node_composition,node_lifecycle,node_elements,node_derivation,node_events toneAmber
class node_judge,node_facts toneMint
class node_composer,node_generator,node_diagnosis,node_presenter toneRose
class node_eventstore,node_llm,node_identity,node_hosting toneIndigo
```

## Components

### User interaction

- [HTTP server](https://github.com/brawliot/abs/blob/main/web/server.ts): `web/server.ts`
- [Action handler](https://github.com/brawliot/abs/blob/main/web/action-handler.ts): `web/action-handler.ts`
- [Intent interpreter](https://github.com/brawliot/abs/blob/main/interpreter/interpret.ts): `interpreter/interpret.ts`
- [UI rendering](https://github.com/brawliot/abs/blob/main/web/render-app.ts): `web/render-app.ts`

### Transaction model

- [Archetype catalog](https://github.com/brawliot/abs/blob/main/archetypes/catalog.ts): `archetypes/catalog.ts`
- [Archetype composition](https://github.com/brawliot/abs/blob/main/archetypes/composition.ts): `archetypes/composition.ts`
- [Lifecycle model](https://github.com/brawliot/abs/blob/main/core/lifecycle.ts): `core/lifecycle.ts`
- [Domain elements](https://github.com/brawliot/abs/blob/main/elements/subtypes.ts): `elements/subtypes.ts`
- [State derivation](https://github.com/brawliot/abs/blob/main/core/derivation.ts): `core/derivation.ts`
- [Domain events](https://github.com/brawliot/abs/blob/main/core/events.ts): `core/events.ts`

### Rules and facts

- [Policy judge](https://github.com/brawliot/abs/blob/main/policies/judge.ts): `policies/judge.ts`
- [Fact provider](https://github.com/brawliot/abs/blob/main/facts/provider.ts): `facts/provider.ts`

### Configuration and insight

- [Process composer](https://github.com/brawliot/abs/blob/main/composer/compose.ts): `composer/compose.ts`
- [Process generator](https://github.com/brawliot/abs/blob/main/generator/generate.ts): `generator/generate.ts`
- [Business diagnosis](https://github.com/brawliot/abs/blob/main/diagnosis/engine.ts): `diagnosis/engine.ts`
- [Insight presenter](https://github.com/brawliot/abs/blob/main/presenter/present.ts): `presenter/present.ts`

### Runtime platform

- [Event store](https://github.com/brawliot/abs/blob/main/core/event-store.ts): `core/event-store.ts`
- [LLM client](https://github.com/brawliot/abs/blob/main/llm/client.ts): `llm/client.ts`
- [Identity and tenancy](https://github.com/brawliot/abs/blob/main/policies/identity.ts): `policies/identity.ts`
- [Tenant routing](https://github.com/brawliot/abs/blob/main/hosting/pool-router.ts): `hosting/pool-router.ts`

### Other components

- **User**

## Connections

- User → HTTP server: submits actions (evidence: `web/server.ts`)
- HTTP server → Action handler: routes actions (evidence: `web/server.ts`)
- HTTP server → UI rendering: renders views (evidence: `web/server.ts`)
- Action handler → Intent interpreter: interprets input (evidence: `web/action-handler.ts`)
- Action handler → Policy judge: requests judgment (evidence: `web/action-handler.ts`)
- Action handler → State derivation: derives current state (evidence: `web/action-handler.ts`)
- Action handler → Archetype composition: checks composition blocks (evidence: `web/action-handler.ts`)
- Action handler → Event store: reads event history (evidence: `web/action-handler.ts`)
- Action handler → Domain events: uses transition events (evidence: `web/action-handler.ts`)
- Archetype catalog → Archetype composition: supplies definitions (evidence: `archetypes/composition.ts`)
- Archetype catalog → Lifecycle model: defines workflows
- Archetype catalog → Domain elements: uses element types
- State derivation → Lifecycle model: derives from lifecycle (evidence: `core/derivation.ts`)
- State derivation → Domain events: derives from events (evidence: `core/derivation.ts`)
- Policy judge → State derivation: checks transition (evidence: `policies/judge.ts`)
- Policy judge → Fact provider: evaluates fact rules (evidence: `policies/judge.ts`)
- Tenant routing → Event store: configures tenant store (evidence: `hosting/pool-router.ts`)
- Tenant routing → Identity and tenancy: configures identity store (evidence: `hosting/pool-router.ts`)
- Business diagnosis → Archetype composition: uses archetype composition (evidence: `diagnosis/engine.ts`)
- Process generator → Business diagnosis: supports process analysis
- Process composer → Process generator: produces process input
- Insight presenter → UI rendering: feeds user-facing insight
- Intent interpreter → LLM client: extracts with LLM