# codingway-hub/a3 architecture

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

- Interactive diagram: https://gitdiagram.com/codingway-hub/a3
- Repository: https://github.com/codingway-hub/a3
- Video tour (about a minute): https://gitdiagram.com/codingway-hub/a3/video

## Overview

a3 audits Claude Code and Codex activity through a terminal collector, applies local pre-tool blocking where supported, and sends events to a server for durable audit, risk scanning, alerts, and administrator review. The main path is log collection → event parsing/masking → batching and offline spool → authenticated ingestion → storage and asynchronous rule scanning → console review or alert notification. The README documents additional management and install/signing capabilities; those are represented at their enclosing source paths where implementation excerpts were not sampled.

Main entry points: [`cmd/agent/pipeline.go`](https://github.com/codingway-hub/a3/blob/main/cmd/agent/pipeline.go) (Collection pipeline), [`internal/server/api/router.go`](https://github.com/codingway-hub/a3/blob/main/internal/server/api/router.go) (HTTP API), [`internal/server/alert/service.go`](https://github.com/codingway-hub/a3/blob/main/internal/server/alert/service.go) (Alert scanning), [`internal/server/store/store.go`](https://github.com/codingway-hub/a3/blob/main/internal/server/store/store.go) (Audit database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collector["Terminal collector"]
  node_agent_cli["Agent commands<br/>[main.go]"]
  node_pipeline["Collection pipeline<br/>[pipeline.go]"]
  node_plugins["Agent plugins"]
  node_tailer["Log tailer<br/>[tailer.go]"]
  node_mask["Event masking<br/>[mask.go]"]
  node_spool[("Offline spool<br/>[spool.go]")]
  node_uploader["Batch uploader<br/>[uploader.go]"]
  node_hook["Pre-tool hook<br/>[rules.go]"]
end

subgraph group_server["Audit server"]
  node_server["HTTP API<br/>[router.go]"]
  node_ingest["Device ingestion<br/>[service.go]"]
  node_auth["Device and user auth"]
  node_rules["Risk rule engine<br/>[engine.go]"]
  node_alerts["Alert scanning<br/>[service.go]"]
  node_store[("Audit database<br/>[store.go]")]
end

subgraph group_console["Admin console"]
  node_webapp["Console application<br/>[App.vue]"]
  node_console_api["Console API client<br/>[console.js]"]
  node_views["Audit and management views"]
end

subgraph group_install["Device onboarding"]
  node_installer["Install and signing routes<br/>[install_routes.go]"]
  node_installer_lib["Install script renderer<br/>[installer.go]"]
end

subgraph group_notify["Alert delivery"]
  node_webhook_worker["Notification worker<br/>[worker.go]"]
  node_webhook["Webhook channel<br/>[webhook.go]"]
end

node_dev(("Developer"))
node_browser(("Administrator"))
node_external_hook(("Webhook service"))

node_dev -->|"runs"| node_agent_cli
node_agent_cli -->|"starts"| node_pipeline
node_pipeline -->|"watches logs"| node_tailer
node_pipeline -->|"selects plugins"| node_plugins
node_tailer -->|"delivers lines"| node_pipeline
node_pipeline -->|"parses lines"| node_plugins
node_pipeline -->|"masks events"| node_mask
node_pipeline -->|"queues batches"| node_spool
node_pipeline -->|"uploads batches"| node_uploader
node_uploader -->|"posts events"| node_server
node_spool -->|"replays batches"| node_uploader
node_agent_cli -->|"dispatches hook"| node_hook
node_hook -->|"queues hook events"| node_spool
node_hook -->|"fetches rules"| node_server
node_server -->|"checks credentials"| node_auth
node_server -->|"dispatches requests"| node_ingest
node_ingest -->|"stores events"| node_store
node_ingest -->|"submits accepted events"| node_alerts
node_alerts -->|"evaluates events"| node_rules
node_alerts -->|"applies scan results"| node_store
node_alerts -->|"queues notifications"| node_webhook_worker
node_webhook_worker -->|"reads outbox"| node_store
node_webhook_worker -->|"sends digest"| node_webhook
node_webhook -.->|"posts alert"| node_external_hook
node_browser -->|"uses console"| node_webapp
node_webapp -->|"requests data"| node_console_api
node_console_api -->|"calls API"| node_server
node_server -->|"reads and writes"| node_store
node_webapp -->|"renders pages"| node_views
node_server -->|"routes install requests"| node_installer
node_installer -->|"renders script"| node_installer_lib
node_dev -->|"requests install"| node_installer

click node_agent_cli "https://github.com/codingway-hub/a3/blob/main/cmd/agent/main.go"
click node_pipeline "https://github.com/codingway-hub/a3/blob/main/cmd/agent/pipeline.go"
click node_plugins "https://github.com/codingway-hub/a3/tree/main/internal/agent/plugins"
click node_tailer "https://github.com/codingway-hub/a3/blob/main/internal/agent/core/watcher/tailer.go"
click node_mask "https://github.com/codingway-hub/a3/blob/main/internal/agent/core/masking/mask.go"
click node_spool "https://github.com/codingway-hub/a3/blob/main/internal/agent/core/spool/spool.go"
click node_uploader "https://github.com/codingway-hub/a3/blob/main/internal/agent/core/transport/uploader.go"
click node_hook "https://github.com/codingway-hub/a3/blob/main/internal/agent/plugins/claude/rules.go"
click node_server "https://github.com/codingway-hub/a3/blob/main/internal/server/api/router.go"
click node_ingest "https://github.com/codingway-hub/a3/blob/main/internal/server/ingest/service.go"
click node_auth "https://github.com/codingway-hub/a3/tree/main/internal/server/auth"
click node_rules "https://github.com/codingway-hub/a3/blob/main/internal/server/rules/engine.go"
click node_alerts "https://github.com/codingway-hub/a3/blob/main/internal/server/alert/service.go"
click node_store "https://github.com/codingway-hub/a3/blob/main/internal/server/store/store.go"
click node_webapp "https://github.com/codingway-hub/a3/blob/main/web/src/App.vue"
click node_console_api "https://github.com/codingway-hub/a3/blob/main/web/src/api/console.js"
click node_views "https://github.com/codingway-hub/a3/tree/main/web/src/views"
click node_installer "https://github.com/codingway-hub/a3/blob/main/internal/server/api/install_routes.go"
click node_installer_lib "https://github.com/codingway-hub/a3/blob/main/internal/server/api/installer/installer.go"
click node_webhook_worker "https://github.com/codingway-hub/a3/blob/main/internal/server/notify/worker.go"
click node_webhook "https://github.com/codingway-hub/a3/blob/main/internal/server/notify/webhook.go"

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_agent_cli,node_pipeline,node_plugins,node_tailer,node_mask,node_spool,node_uploader,node_hook toneBlue
class node_server,node_ingest,node_auth,node_rules,node_alerts,node_store toneAmber
class node_webapp,node_console_api,node_views,node_external_hook toneMint
class node_installer,node_installer_lib toneRose
class node_webhook_worker,node_webhook,node_dev,node_browser toneIndigo
```

## Components

### Terminal collector

- [Agent commands](https://github.com/codingway-hub/a3/blob/main/cmd/agent/main.go): `cmd/agent/main.go`
- [Collection pipeline](https://github.com/codingway-hub/a3/blob/main/cmd/agent/pipeline.go): `cmd/agent/pipeline.go`
- [Agent plugins](https://github.com/codingway-hub/a3/tree/main/internal/agent/plugins): `internal/agent/plugins`
- [Log tailer](https://github.com/codingway-hub/a3/blob/main/internal/agent/core/watcher/tailer.go): `internal/agent/core/watcher/tailer.go`
- [Event masking](https://github.com/codingway-hub/a3/blob/main/internal/agent/core/masking/mask.go): `internal/agent/core/masking/mask.go`
- [Offline spool](https://github.com/codingway-hub/a3/blob/main/internal/agent/core/spool/spool.go): `internal/agent/core/spool/spool.go`
- [Batch uploader](https://github.com/codingway-hub/a3/blob/main/internal/agent/core/transport/uploader.go): `internal/agent/core/transport/uploader.go`
- [Pre-tool hook](https://github.com/codingway-hub/a3/blob/main/internal/agent/plugins/claude/rules.go): `internal/agent/plugins/claude/rules.go`

### Audit server

- [HTTP API](https://github.com/codingway-hub/a3/blob/main/internal/server/api/router.go): `internal/server/api/router.go`
- [Device ingestion](https://github.com/codingway-hub/a3/blob/main/internal/server/ingest/service.go): `internal/server/ingest/service.go`
- [Device and user auth](https://github.com/codingway-hub/a3/tree/main/internal/server/auth): `internal/server/auth`
- [Risk rule engine](https://github.com/codingway-hub/a3/blob/main/internal/server/rules/engine.go): `internal/server/rules/engine.go`
- [Alert scanning](https://github.com/codingway-hub/a3/blob/main/internal/server/alert/service.go): `internal/server/alert/service.go`
- [Audit database](https://github.com/codingway-hub/a3/blob/main/internal/server/store/store.go): `internal/server/store/store.go`

### Admin console

- [Console application](https://github.com/codingway-hub/a3/blob/main/web/src/App.vue): `web/src/App.vue`
- [Console API client](https://github.com/codingway-hub/a3/blob/main/web/src/api/console.js): `web/src/api/console.js`
- [Audit and management views](https://github.com/codingway-hub/a3/tree/main/web/src/views): `web/src/views`

### Device onboarding

- [Install and signing routes](https://github.com/codingway-hub/a3/blob/main/internal/server/api/install_routes.go): `internal/server/api/install_routes.go`
- [Install script renderer](https://github.com/codingway-hub/a3/blob/main/internal/server/api/installer/installer.go): `internal/server/api/installer/installer.go`

### Alert delivery

- [Notification worker](https://github.com/codingway-hub/a3/blob/main/internal/server/notify/worker.go): `internal/server/notify/worker.go`
- [Webhook channel](https://github.com/codingway-hub/a3/blob/main/internal/server/notify/webhook.go): `internal/server/notify/webhook.go`

### Other components

- **Developer**
- **Administrator**
- **Webhook service**

## Connections

- Developer → Agent commands: runs
- Agent commands → Collection pipeline: starts
- Collection pipeline → Log tailer: watches logs
- Collection pipeline → Agent plugins: selects plugins
- Log tailer → Collection pipeline: delivers lines
- Collection pipeline → Agent plugins: parses lines
- Collection pipeline → Event masking: masks events
- Collection pipeline → Offline spool: queues batches
- Collection pipeline → Batch uploader: uploads batches
- Batch uploader → HTTP API: posts events
- Offline spool → Batch uploader: replays batches
- Agent commands → Pre-tool hook: dispatches hook
- Pre-tool hook → Offline spool: queues hook events
- Pre-tool hook → HTTP API: fetches rules
- HTTP API → Device and user auth: checks credentials
- HTTP API → Device ingestion: dispatches requests
- Device ingestion → Audit database: stores events
- Device ingestion → Alert scanning: submits accepted events
- Alert scanning → Risk rule engine: evaluates events
- Alert scanning → Audit database: applies scan results
- Alert scanning → Notification worker: queues notifications
- Notification worker → Audit database: reads outbox
- Notification worker → Webhook channel: sends digest
- Webhook channel → Webhook service: posts alert
- Administrator → Console application: uses console
- Console application → Console API client: requests data
- Console API client → HTTP API: calls API
- HTTP API → Audit database: reads and writes
- Console application → Audit and management views: renders pages
- HTTP API → Install and signing routes: routes install requests
- Install and signing routes → Install script renderer: renders script
- Developer → Install and signing routes: requests install