Back to flagship systems

Case study / Multi-language monitoring pipeline

Agent Activity Risk Monitor

A TypeScript ingestion service and Python analyzer that coordinate through PostgreSQL to turn agent activity events into idempotent, queryable risk alerts.

Private sourceSynthetic demo
  • Five risk rules
  • Two services
  • 47 unit tests
  • 38 end-to-end tests
  • TypeScript
  • Fastify
  • Python
  • PostgreSQL
  • SQL
  • Docker
  • Zod

Guided case study

Follow one event across two services.

Move through the reasoning in six short chapters, or read every chapter with JavaScript disabled.

01 / Problem

Make agent activity inspectable after it happens.

The monitor receives structured activity events, identifies risky patterns, and exposes alerts, summaries, and a timeline that an operator can query.

02 / Constraints

Delivery and analysis are both repeatable.

Agents retry events, multiple analyzers may claim work, some rules need history, and the event clock can differ from the time the monitor received it.

03 / Architecture

PostgreSQL is the explicit integration point.

Fastify validates and stores events, Python claims unanalysed rows and writes alerts, and the read API serves both. Shared migrations define the contract between the two languages.

04 / Decisions

Database constraints carry the retry guarantees.

Event IDs are unique, alerts are unique by event and rule, and FOR UPDATE SKIP LOCKED lets concurrent analyzers claim different rows without duplicating work.

05 / Evidence

Fast rules and full-system tests cover different risks.

Forty-seven unit tests cover pure rules and ingestion validation. Thirty-eight end-to-end tests cross the HTTP, TypeScript, Python, migration, and PostgreSQL seams.

06 / Limits

The current design chooses simplicity over real-time delivery.

The analyzer polls and both services know the shared schema. The portfolio demonstration uses synthetic event labels only and never runs an action or sends activity elsewhere.

Chapter 1 of 6: Problem.

Synthetic event pipeline

Send an event. Trace what the monitor keeps.

The demonstration uses safe event labels only. It never executes a tool, opens a file, or makes a network request.

event_idevt-demo-104agent_idagent-demo-7typefile_read

A synthetic agent reads a normal file inside its project workspace.

Received
1
Stored
1
Alerts
0

Selected stage

Ingest

Fastify validates the file_read envelope and attributes it to synthetic agent agent-demo-7.

ClearNo alert raised for the ordinary synthetic event.

Synthetic event stored and analysed. No alert was raised.

01 / Engineering problem

Retries and concurrency cannot change the evidence.

Agent events can arrive more than once, analysis can run concurrently, and rules need both one-event patterns and recent history. The system must preserve cause and effect across those boundaries.

02 / Durable decisions

The database carries the cross-language guarantees.

Built the Fastify ingestion and read API, Python rule engine, shared schema and migrations, safe concurrent claiming, alert idempotency, container workflow, and HTTP-level end-to-end coverage.

01

Let constraints enforce idempotency

Events use event_id as the primary key and alerts are unique on event_id plus rule, closing race windows around retries.

02

Claim work without a global lock

FOR UPDATE SKIP LOCKED gives concurrent analyzers different rows and keeps event completion with alert writes in one transaction.

03

Keep rules pure

Each rule receives the event, approved domains, and any required history, then returns a finding without performing IO.

04

Preserve two clocks

occurred_at represents the agent clock, while received_at keeps the operator timeline in cause-before-effect order.

03 / What this demonstrates

A system boundary shared without hiding the trade-offs.

The monitor connects TypeScript, Python, SQL, concurrency control, validation, and operations while keeping every public interaction synthetic and safe.

Discuss a monitoring system