Architecture

Overview

Techlog is designed around one event store and one API. Collectors and AI agents write events through the same validation path, workflows and policies read from the store, and every client (the MCP server, the query API, a UI) reads the same data. The core of this design runs today as a single Go server, described under what runs today. Collectors, the workflow engine, and policy evaluation are still proposals; this page marks which is which.

flowchart TB
  SRC[External tools]
  AG[AI agents]
  subgraph TL[Techlog]
    MCP[MCP server]
    ING[Event ingestion and schema validation]
    STORE[(Event store and evidence references)]
    API[Query API]
    WF[Workflow engine]
    POL[Policy evaluation]
    AUD[Audit records]
  end
  DEP[CI/CD and deployment systems]
  SRC ~~~ AG
  SRC -- collectors, webhooks --> ING
  AG --> MCP --> ING
  ING --> STORE
  STORE --> API
  STORE --> WF --> POL --> AUD
  POL -. outcome .-> DEP

External tools are Git hosting, issue trackers, CI/CD, observability, and incident tools. Read the diagram top to bottom: events come in from tools and agents, are validated and stored, and are then read by the query API and the workflow and policy engines. The MCP server also reads through the query API; that line is left out to keep the picture clear.

Every section below describes a proposed design.

What runs today

One binary, techlog, serves three front doors on one port, and all three call the same service layer:

• HTTP API at /api/v1: record, get, search, link, and read system history.
• MCP server at /mcp: five tools over streamable HTTP. See MCP integration.
• Web UI at /: read-only event list, event pages, system timelines, and story walkthroughs.

The service validates every event against the JSON Schema (see what the server adds to the schema), then writes it through a small storage interface. The interface has one implementation, SQLite, and a contract test suite that any further backend must pass. Events are immutable; links added later are stored beside them. See Run the server.

Not part of that core yet: collectors for git, CI, deployment, and alerting; the workflow engine; policy evaluation; event signatures; authentication and authorization.

Event ingestion

Collectors and webhooks turn activity in external tools into events. Ingestion is idempotent by source reference, so a webhook delivered twice records one event. Every event is validated against the schema before it is written, and an invalid event is rejected with a structured error.

Event schema

The schema is the contract between everything else. See the event model.

Lifecycle relationships

Links are stored with the event that makes the claim. Inbound links are derived, so a release can show every incident observed after it without any event being edited. See the lifecycle model.

Evidence storage and references

Techlog stores references and digests, not artifacts. A test report stays in the CI system, a dashboard stays in the observability tool, and the owning tool decides how long they live and who may read them. The event holds the reference and, optionally, the digest recorded at collection time.

Workflow engine

A workflow reacts to events: a trigger matches, state is kept, and the next step runs, such as asking for an approval or opening a follow-up action. State lives in events, so a workflow can be rebuilt from the store.

Policy evaluation

A policy takes events and evidence as input and produces an outcome: compliant, missing evidence, approval required, or blocked. Evaluating a policy and enforcing it are separate. Enforcement needs an integration with the system that performs the operation. See workflow and policy.

MCP server

The MCP server exposes tools over the same ingestion path and query API, so an agent gets the same validation as any other client. Today there are five tools; resources, prompts, and permissions per client are proposed. See MCP integration.

External integrations

Collectors that only read from a tool come first. Integrations that write back, such as a status check on a deployment, come later and are authorized separately, with their own threat model.

Status