# quantdale/night-watch architecture

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

- Interactive diagram: https://gitdiagram.com/quantdale/night-watch
- Repository: https://github.com/quantdale/night-watch

## Overview

Nightwatch is a private, local autonomous bug-hunting framework. Its main workflow contains browser activity, observes and records evidence, then minimizes and triages failures into private, owner-reviewable findings; operators inspect those findings in the Control Center. Major parallel capabilities include authenticated-session handling, source and semantic coverage analysis, campaign planning, and explicit outbound-network containment. The graph follows documented behavior and indexed imports; several substantial subsystems are represented at their exact enclosing directories because their implementation files were not sampled.

Main entry points: [`src/browser/context.ts`](https://github.com/quantdale/night-watch/blob/main/src/browser/context.ts) (Browser Harness), [`src/browser/observers/networkObserver.ts`](https://github.com/quantdale/night-watch/blob/main/src/browser/observers/networkObserver.ts) (Network Observer), [`src/core/triage/pipeline.ts`](https://github.com/quantdale/night-watch/blob/main/src/core/triage/pipeline.ts) (Failure Triage), [`src/core/policy/privateArtifacts.ts`](https://github.com/quantdale/night-watch/blob/main/src/core/policy/privateArtifacts.ts) (Artifact Policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Local Investigation"]
  node_browser["Browser Harness<br/>[context.ts]"]
  node_journeys["Journey Executor<br/>[engine.ts]"]
  node_exploration["Exploration Engine<br/>[engine.ts]"]
  node_campaign["Campaign Runtime"]
  node_auth["Authentication"]
end

subgraph group_evidence["Evidence and Triage"]
  node_observer["Network Observer<br/>[networkObserver.ts]"]
  node_recorder["Run Evidence<br/>[runRecorder.ts]"]
  node_triage["Failure Triage<br/>[pipeline.ts]"]
  node_private[("Private Artifacts")]
  node_finding["Finding Dossiers"]
end

subgraph group_intelligence["Analysis and Campaigns"]
  node_coverage["Source Coverage"]
  node_php["PHP Analysis<br/>[phpPipeline.ts]"]
  node_semantic["Semantic Coverage"]
  node_campaignintel["Campaign Intelligence"]
end

subgraph group_safety["Safety and Policy"]
  node_policy["Outbound Policy<br/>[outboundPolicy.ts]"]
  node_proxy["Loopback Proxy<br/>[server.ts]"]
  node_privatepolicy["Artifact Policy"]
end

subgraph group_review["Owner Review"]
  node_ai["AI Review<br/>[pipeline.ts]"]
  node_controlserver["Control Center API<br/>[server.ts]"]
  node_authority["Finding Authority"]
  node_reviewer["Reviewer Projection<br/>[reviewerAdapter.ts]"]
  node_ui["Control Center UI<br/>[App.tsx]"]
end

node_operator(("Operator"))

node_operator -->|"runs locally"| node_browser
node_operator -->|"captures session"| node_auth
node_browser -->|"observes requests"| node_observer
node_browser -->|"records evidence"| node_recorder
node_journeys -->|"waits for observations"| node_observer
node_exploration -.->|"executes actions"| node_browser
node_campaign -.->|"coordinates runs"| node_exploration
node_observer -->|"checks requests"| node_policy
node_proxy -->|"classifies requests"| node_policy
node_observer -->|"records observations"| node_recorder
node_triage -->|"checks write policy"| node_privatepolicy
node_triage -.->|"produces dossiers"| node_finding
node_triage -.->|"persists artifacts"| node_private
node_private -->|"uses storage policy"| node_privatepolicy
node_coverage -->|"analyzes PHP"| node_php
node_php -->|"uses coverage analysis"| node_semantic
node_campaign -.->|"uses intelligence"| node_campaignintel
node_ai -->|"checks owner scope"| node_privatepolicy
node_controlserver -.->|"routes findings"| node_authority
node_authority -->|"supplies findings"| node_reviewer
node_ui -.->|"loads API data"| node_controlserver
node_operator -.->|"reviews findings"| node_ui

click node_browser "https://github.com/quantdale/night-watch/blob/main/src/browser/context.ts"
click node_journeys "https://github.com/quantdale/night-watch/blob/main/src/core/journeys/engine.ts"
click node_exploration "https://github.com/quantdale/night-watch/blob/main/src/core/exploration/engine.ts"
click node_campaign "https://github.com/quantdale/night-watch/tree/main/src/core/campaign"
click node_auth "https://github.com/quantdale/night-watch/tree/main/src/auth"
click node_observer "https://github.com/quantdale/night-watch/blob/main/src/browser/observers/networkObserver.ts"
click node_recorder "https://github.com/quantdale/night-watch/blob/main/src/core/evidence/runRecorder.ts"
click node_triage "https://github.com/quantdale/night-watch/blob/main/src/core/triage/pipeline.ts"
click node_private "https://github.com/quantdale/night-watch/blob/main/src/core/policy/privateArtifacts.ts"
click node_finding "https://github.com/quantdale/night-watch/tree/main/src/core/autonomousFinding"
click node_coverage "https://github.com/quantdale/night-watch/blob/main/src/oracles/expectations/coverageInventory.ts"
click node_php "https://github.com/quantdale/night-watch/blob/main/src/core/source/phpPipeline.ts"
click node_semantic "https://github.com/quantdale/night-watch/tree/main/src/core/semanticCoverage"
click node_campaignintel "https://github.com/quantdale/night-watch/tree/main/src/core/campaignIntelligence"
click node_policy "https://github.com/quantdale/night-watch/blob/main/src/core/safety/outboundPolicy.ts"
click node_proxy "https://github.com/quantdale/night-watch/blob/main/src/proxy/server.ts"
click node_privatepolicy "https://github.com/quantdale/night-watch/blob/main/src/core/policy/privateArtifacts.ts"
click node_ai "https://github.com/quantdale/night-watch/blob/main/src/core/aiReview/pipeline.ts"
click node_controlserver "https://github.com/quantdale/night-watch/blob/main/src/controlCenter/server/server.ts"
click node_authority "https://github.com/quantdale/night-watch/blob/main/src/controlCenter/authorities/findingsAuthority.ts"
click node_reviewer "https://github.com/quantdale/night-watch/blob/main/src/controlCenter/adapters/reviewerAdapter.ts"
click node_ui "https://github.com/quantdale/night-watch/blob/main/ui/control-center/src/App.tsx"

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_browser,node_journeys,node_exploration,node_campaign,node_auth toneBlue
class node_observer,node_recorder,node_triage,node_private,node_finding toneAmber
class node_coverage,node_php,node_semantic,node_campaignintel toneMint
class node_policy,node_proxy,node_privatepolicy toneRose
class node_ai,node_controlserver,node_authority,node_reviewer,node_ui,node_operator toneIndigo
```

## Components

### Local Investigation

- [Browser Harness](https://github.com/quantdale/night-watch/blob/main/src/browser/context.ts): `src/browser/context.ts`
- [Journey Executor](https://github.com/quantdale/night-watch/blob/main/src/core/journeys/engine.ts): `src/core/journeys/engine.ts`
- [Exploration Engine](https://github.com/quantdale/night-watch/blob/main/src/core/exploration/engine.ts): `src/core/exploration/engine.ts`
- [Campaign Runtime](https://github.com/quantdale/night-watch/tree/main/src/core/campaign): `src/core/campaign`
- [Authentication](https://github.com/quantdale/night-watch/tree/main/src/auth): `src/auth`

### Evidence and Triage

- [Network Observer](https://github.com/quantdale/night-watch/blob/main/src/browser/observers/networkObserver.ts): `src/browser/observers/networkObserver.ts`
- [Run Evidence](https://github.com/quantdale/night-watch/blob/main/src/core/evidence/runRecorder.ts): `src/core/evidence/runRecorder.ts`
- [Failure Triage](https://github.com/quantdale/night-watch/blob/main/src/core/triage/pipeline.ts): `src/core/triage/pipeline.ts`
- [Private Artifacts](https://github.com/quantdale/night-watch/blob/main/src/core/policy/privateArtifacts.ts): `src/core/policy/privateArtifacts.ts`
- [Finding Dossiers](https://github.com/quantdale/night-watch/tree/main/src/core/autonomousFinding): `src/core/autonomousFinding`

### Analysis and Campaigns

- [Source Coverage](https://github.com/quantdale/night-watch/blob/main/src/oracles/expectations/coverageInventory.ts): `src/oracles/expectations/coverageInventory.ts`
- [PHP Analysis](https://github.com/quantdale/night-watch/blob/main/src/core/source/phpPipeline.ts): `src/core/source/phpPipeline.ts`
- [Semantic Coverage](https://github.com/quantdale/night-watch/tree/main/src/core/semanticCoverage): `src/core/semanticCoverage`
- [Campaign Intelligence](https://github.com/quantdale/night-watch/tree/main/src/core/campaignIntelligence): `src/core/campaignIntelligence`

### Safety and Policy

- [Outbound Policy](https://github.com/quantdale/night-watch/blob/main/src/core/safety/outboundPolicy.ts): `src/core/safety/outboundPolicy.ts`
- [Loopback Proxy](https://github.com/quantdale/night-watch/blob/main/src/proxy/server.ts): `src/proxy/server.ts`
- [Artifact Policy](https://github.com/quantdale/night-watch/blob/main/src/core/policy/privateArtifacts.ts): `src/core/policy/privateArtifacts.ts`

### Owner Review

- [AI Review](https://github.com/quantdale/night-watch/blob/main/src/core/aiReview/pipeline.ts): `src/core/aiReview/pipeline.ts`
- [Control Center API](https://github.com/quantdale/night-watch/blob/main/src/controlCenter/server/server.ts): `src/controlCenter/server/server.ts`
- [Finding Authority](https://github.com/quantdale/night-watch/blob/main/src/controlCenter/authorities/findingsAuthority.ts): `src/controlCenter/authorities/findingsAuthority.ts`
- [Reviewer Projection](https://github.com/quantdale/night-watch/blob/main/src/controlCenter/adapters/reviewerAdapter.ts): `src/controlCenter/adapters/reviewerAdapter.ts`
- [Control Center UI](https://github.com/quantdale/night-watch/blob/main/ui/control-center/src/App.tsx): `ui/control-center/src/App.tsx`

### Other components

- **Operator**

## Connections

- Operator → Browser Harness: runs locally (evidence: `README.md`)
- Operator → Authentication: captures session (evidence: `README.md`)
- Browser Harness → Network Observer: observes requests (evidence: `src/browser/context.ts`)
- Browser Harness → Run Evidence: records evidence (evidence: `src/browser/context.ts`)
- Journey Executor → Network Observer: waits for observations (evidence: `src/core/journeys/engine.ts`)
- Exploration Engine → Browser Harness: executes actions
- Campaign Runtime → Exploration Engine: coordinates runs
- Network Observer → Outbound Policy: checks requests (evidence: `src/browser/observers/networkObserver.ts`)
- Loopback Proxy → Outbound Policy: classifies requests (evidence: `src/proxy/server.ts`)
- Network Observer → Run Evidence: records observations (evidence: `src/browser/observers/networkObserver.ts`)
- Failure Triage → Artifact Policy: checks write policy (evidence: `src/core/triage/pipeline.ts`)
- Failure Triage → Finding Dossiers: produces dossiers
- Failure Triage → Private Artifacts: persists artifacts (evidence: `src/core/triage/pipeline.ts`)
- Private Artifacts → Artifact Policy: uses storage policy (evidence: `src/core/selfDev/storage.ts`)
- Source Coverage → PHP Analysis: analyzes PHP (evidence: `src/oracles/expectations/coverageInventory.ts`)
- PHP Analysis → Semantic Coverage: uses coverage analysis (evidence: `src/core/source/phpPipeline.ts`)
- Campaign Runtime → Campaign Intelligence: uses intelligence
- AI Review → Artifact Policy: checks owner scope (evidence: `src/core/aiReview/pipeline.ts`)
- Control Center API → Finding Authority: routes findings
- Finding Authority → Reviewer Projection: supplies findings (evidence: `src/controlCenter/authorities/findingsAuthority.ts`)
- Control Center UI → Control Center API: loads API data
- Operator → Control Center UI: reviews findings