WRIT Docs

#Architecture Overview

WRIT is a monorepo containing several components that work together to detect and surface misalignment. This page describes the two primary components covered by this documentation: kbpy and writ-kb.

#Component Diagram

graph TD
  subgraph mono["WRIT Monorepo"]
    kbpy["kbpy (Python)<br/>Domain DSL · Evaluation · Web Server"]
    proxy["Proxy (Clojure)<br/>Data Ingestion"]
    transactor["Transactor (Clojure)<br/>Persistence Layer"]
    writkb["writ-kb (Remix)<br/>KB Viewer · Dashboard"]
    writdocs["writ-docs (Remix)<br/>Docs Site (this site)"]

    kbpy --> proxy --> transactor
    kbpy -- "materialised state" --> writkb
  end
  style kbpy fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style proxy fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style transactor fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style writkb fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style writdocs fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style mono fill:#f8fafc,stroke:#94a3b8,color:#334155

#kbpy — The Knowledge Base Engine

kbpy is a Python application that serves as the core evaluation engine. It:

  • Parses domain definitions written in a custom DSL (.kb files) that describe entity types, attributes, relationships, partitions, and expectations.
  • Loads attestation data from CSV files or external sources, treating them as evidence of what is currently true.
  • Evaluates expectations using three-valued logic (Kleene K3), producing results of true, false, or unknown for each entity against each expectation.
  • Generates questions when data is missing (unknown) and actions when expectations are not met (false).
  • Serves results via a web interface (default port 1234) and materialises state for downstream consumers.

#Data Flow Through kbpy

graph TD
  KB[".kb files"] --> Parser --> DM["Domain Model"]
  CSV["CSV / API data"] --> AS["Attestation Sources"] --> ES["Entity Sets"]
  DM --> P["Partitions<br/>(classify entities via predicates)"]
  ES --> P
  P --> EX["Expectations<br/>(evaluate against partition branches)"]
  EX --> Q["Questions<br/>(unknown)"]
  EX --> Act["Actions<br/>(false)"]
  EX --> S["Status<br/>(true / met)"]
  style KB fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style Parser fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style DM fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style CSV fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style AS fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style ES fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style P fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style EX fill:#ecfeff,stroke:#06B6D4,color:#0e7490
  style Q fill:#fef3c7,stroke:#f59e0b,color:#92400e
  style Act fill:#fef3c7,stroke:#f59e0b,color:#92400e
  style S fill:#d1fae5,stroke:#10b981,color:#065f46

#writ-kb — The Web Application

writ-kb is a Remix application that provides a visual interface for exploring domain state. It:

  • Reads materialised state from kbpy via a SQLite database.
  • Displays domains with their entity types, entity sets, and relationships.
  • Visualises expectations showing which are met, not met, or uncertain.
  • Shows the evaluation pipeline from data sources through partitions to expectations.

writ-kb runs on port 3100 by default.

#How They Connect

The data flow between components is unidirectional:

  1. kbpy evaluates domains and materialises results.
  2. writ-kb reads the materialised state and renders it.
  3. Users interact with writ-kb to understand the current state of their expectations.

This separation means kbpy can run independently (useful for development and testing), while writ-kb provides the visual layer on top of kbpy's outputs.

#Development Ports

Service Port Description
kbpy web 1234 kbpy's built-in web server
writ-kb 3100 Remix application for KB visualisation
writ-docs 3200 Documentation site (this site)
Proxy 3001 Data ingestion proxy

#Next Steps