# popla69/pic architecture

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

- Interactive diagram: https://gitdiagram.com/popla69/pic
- Repository: https://github.com/popla69/pic

## Overview

PIC is an in-process defensive framework that monitors application functions, evaluates telemetry for security and behavioral anomalies, and allows or blocks activity. The principal workflow is application call → CellAgent telemetry → BrainConnector → BrainCore decision, with state, trace, and signed audit persistence. Its documented adaptive learning, cryptographic validation, and real-world testbench are also represented. Edges reflect the excerpts, SOURCE INDEX references, or README; uninspected implementation details are omitted or left unconnected.

Main entry points: [`src/pic/brain/core.py`](https://github.com/popla69/pic/blob/main/src/pic/brain/core.py) (BrainCore), [`src/pic/integrated.py`](https://github.com/popla69/pic/blob/main/src/pic/integrated.py) (Integrated PIC), [`src/pic/realworld/harness.py`](https://github.com/popla69/pic/blob/main/src/pic/realworld/harness.py) (Test Harness), [`src/pic/realworld/suite.py`](https://github.com/popla69/pic/blob/main/src/pic/realworld/suite.py) (Test Suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Monitoring Runtime"]
  node_integrated["Integrated PIC<br/>[integrated.py]"]
  node_agent["CellAgent<br/>[agent.py]"]
  node_connector["Brain Connector<br/>[brain_connector.py]"]
  node_config["Configuration<br/>[loader.py]"]
  node_redaction["PII Redaction<br/>[redaction.py]"]
  node_rate["Rate Limiting<br/>[rate_limiter.py]"]
end

subgraph group_analysis["Detection Engine"]
  node_brain["BrainCore<br/>[core.py]"]
  node_anomaly["Anomaly Detection<br/>[detector.py]"]
  node_profiling["Baseline Profiling<br/>[profiler.py]"]
  node_patterns["Pattern Cache<br/>[pattern_cache.py]"]
  node_normalizer["Event Normalization<br/>[normalizer.py]"]
  node_validator["Security Validation"]
  node_effector["Action Executor<br/>[executor.py]"]
end

subgraph group_state["State and Security"]
  node_crypto["HMAC Crypto<br/>[core.py]"]
  node_state_store[("Baseline State<br/>[state_store.py]")]
  node_trace_store[("Event Traces<br/>[trace_store.py]")]
  node_audit_store[("Signed Audit Log<br/>[audit_store.py]")]
end

subgraph group_testing["Real-World Testbench"]
  node_suite["Test Suite<br/>[suite.py]"]
  node_harness["Test Harness<br/>[harness.py]"]
  node_safety["Safety Controls<br/>[safety.py]"]
  node_sandbox["Sandbox<br/>[sandbox.py]"]
  node_reporting["Test Reporting<br/>[reporting.py]"]
  node_testers["Attack Scenarios"]
end

subgraph group_models["Shared Data Models"]
  node_telemetry["Telemetry Events<br/>[events.py]"]
  node_decisions["Security Decisions<br/>[decision.py]"]
  node_integration_models["Signed Messages<br/>[integration.py]"]
end

node_developer(("Application User"))

node_developer -->|"starts monitoring"| node_integrated
node_integrated -->|"initializes"| node_agent
node_integrated -->|"initializes"| node_brain
node_integrated -->|"connects"| node_connector
node_integrated -->|"initializes"| node_state_store
node_integrated -->|"initializes"| node_audit_store
node_integrated -->|"initializes"| node_trace_store
node_agent -->|"sends events"| node_connector
node_agent -->|"redacts data"| node_redaction
node_agent -->|"limits traffic"| node_rate
node_connector -->|"forwards events"| node_brain
node_brain -->|"validates signatures"| node_validator
node_brain -->|"stores events"| node_trace_store
node_brain -->|"reads baselines"| node_state_store
node_brain -->|"normalizes events"| node_normalizer
node_brain -->|"detects anomalies"| node_anomaly
node_brain -->|"profiles baselines"| node_profiling
node_brain -->|"checks patterns"| node_patterns
node_brain -->|"executes action"| node_effector
node_brain -->|"logs decisions"| node_audit_store
node_audit_store -->|"signs entries"| node_crypto
node_brain -->|"processes events"| node_telemetry
node_brain -->|"returns decisions"| node_decisions
node_connector -->|"uses messages"| node_integration_models
node_integrated -->|"loads settings"| node_config
node_suite -->|"runs through"| node_harness
node_suite -->|"applies controls"| node_safety
node_suite -->|"uses sandbox"| node_sandbox
node_suite -->|"produces reports"| node_reporting
node_suite -->|"dispatches scenarios"| node_testers
node_harness -->|"checks safety"| node_safety
node_harness -->|"uses sandbox"| node_sandbox
node_harness -->|"exercises engine"| node_brain
node_harness -->|"uses state"| node_state_store
node_harness -->|"uses audit log"| node_audit_store
node_harness -->|"uses traces"| node_trace_store

click node_integrated "https://github.com/popla69/pic/blob/main/src/pic/integrated.py"
click node_agent "https://github.com/popla69/pic/blob/main/src/pic/cellagent/agent.py"
click node_connector "https://github.com/popla69/pic/blob/main/src/pic/cellagent/brain_connector.py"
click node_config "https://github.com/popla69/pic/blob/main/src/pic/config/loader.py"
click node_redaction "https://github.com/popla69/pic/blob/main/src/pic/cellagent/redaction.py"
click node_rate "https://github.com/popla69/pic/blob/main/src/pic/cellagent/rate_limiter.py"
click node_brain "https://github.com/popla69/pic/blob/main/src/pic/brain/core.py"
click node_anomaly "https://github.com/popla69/pic/blob/main/src/pic/brain/detector.py"
click node_profiling "https://github.com/popla69/pic/blob/main/src/pic/brain/profiler.py"
click node_patterns "https://github.com/popla69/pic/blob/main/src/pic/brain/pattern_cache.py"
click node_normalizer "https://github.com/popla69/pic/blob/main/src/pic/brain/normalizer.py"
click node_validator "https://github.com/popla69/pic/blob/main/src/pic/brain/security_validator.py"
click node_effector "https://github.com/popla69/pic/blob/main/src/pic/effector/executor.py"
click node_crypto "https://github.com/popla69/pic/blob/main/src/pic/crypto/core.py"
click node_state_store "https://github.com/popla69/pic/blob/main/src/pic/storage/state_store.py"
click node_trace_store "https://github.com/popla69/pic/blob/main/src/pic/storage/trace_store.py"
click node_audit_store "https://github.com/popla69/pic/blob/main/src/pic/storage/audit_store.py"
click node_telemetry "https://github.com/popla69/pic/blob/main/src/pic/models/events.py"
click node_decisions "https://github.com/popla69/pic/blob/main/src/pic/models/decision.py"
click node_integration_models "https://github.com/popla69/pic/blob/main/src/pic/models/integration.py"
click node_suite "https://github.com/popla69/pic/blob/main/src/pic/realworld/suite.py"
click node_harness "https://github.com/popla69/pic/blob/main/src/pic/realworld/harness.py"
click node_safety "https://github.com/popla69/pic/blob/main/src/pic/realworld/safety.py"
click node_sandbox "https://github.com/popla69/pic/blob/main/src/pic/realworld/sandbox.py"
click node_reporting "https://github.com/popla69/pic/blob/main/src/pic/realworld/reporting.py"
click node_testers "https://github.com/popla69/pic/tree/main/src/pic/realworld/testers"

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_integrated,node_agent,node_connector,node_config,node_redaction,node_rate,node_developer toneBlue
class node_brain,node_anomaly,node_profiling,node_patterns,node_normalizer,node_validator,node_effector toneAmber
class node_crypto,node_state_store,node_trace_store,node_audit_store toneMint
class node_suite,node_harness,node_safety,node_sandbox,node_reporting,node_testers toneRose
class node_telemetry,node_decisions,node_integration_models toneIndigo
```

## Components

### Monitoring Runtime

- [Integrated PIC](https://github.com/popla69/pic/blob/main/src/pic/integrated.py): `src/pic/integrated.py`
- [CellAgent](https://github.com/popla69/pic/blob/main/src/pic/cellagent/agent.py): `src/pic/cellagent/agent.py`
- [Brain Connector](https://github.com/popla69/pic/blob/main/src/pic/cellagent/brain_connector.py): `src/pic/cellagent/brain_connector.py`
- [Configuration](https://github.com/popla69/pic/blob/main/src/pic/config/loader.py): `src/pic/config/loader.py`
- [PII Redaction](https://github.com/popla69/pic/blob/main/src/pic/cellagent/redaction.py): `src/pic/cellagent/redaction.py`
- [Rate Limiting](https://github.com/popla69/pic/blob/main/src/pic/cellagent/rate_limiter.py): `src/pic/cellagent/rate_limiter.py`

### Detection Engine

- [BrainCore](https://github.com/popla69/pic/blob/main/src/pic/brain/core.py): `src/pic/brain/core.py`
- [Anomaly Detection](https://github.com/popla69/pic/blob/main/src/pic/brain/detector.py): `src/pic/brain/detector.py`
- [Baseline Profiling](https://github.com/popla69/pic/blob/main/src/pic/brain/profiler.py): `src/pic/brain/profiler.py`
- [Pattern Cache](https://github.com/popla69/pic/blob/main/src/pic/brain/pattern_cache.py): `src/pic/brain/pattern_cache.py`
- [Event Normalization](https://github.com/popla69/pic/blob/main/src/pic/brain/normalizer.py): `src/pic/brain/normalizer.py`
- [Security Validation](https://github.com/popla69/pic/blob/main/src/pic/brain/security_validator.py): `src/pic/brain/security_validator.py`
- [Action Executor](https://github.com/popla69/pic/blob/main/src/pic/effector/executor.py): `src/pic/effector/executor.py`

### State and Security

- [HMAC Crypto](https://github.com/popla69/pic/blob/main/src/pic/crypto/core.py): `src/pic/crypto/core.py`
- [Baseline State](https://github.com/popla69/pic/blob/main/src/pic/storage/state_store.py): `src/pic/storage/state_store.py`
- [Event Traces](https://github.com/popla69/pic/blob/main/src/pic/storage/trace_store.py): `src/pic/storage/trace_store.py`
- [Signed Audit Log](https://github.com/popla69/pic/blob/main/src/pic/storage/audit_store.py): `src/pic/storage/audit_store.py`

### Real-World Testbench

- [Test Suite](https://github.com/popla69/pic/blob/main/src/pic/realworld/suite.py): `src/pic/realworld/suite.py`
- [Test Harness](https://github.com/popla69/pic/blob/main/src/pic/realworld/harness.py): `src/pic/realworld/harness.py`
- [Safety Controls](https://github.com/popla69/pic/blob/main/src/pic/realworld/safety.py): `src/pic/realworld/safety.py`
- [Sandbox](https://github.com/popla69/pic/blob/main/src/pic/realworld/sandbox.py): `src/pic/realworld/sandbox.py`
- [Test Reporting](https://github.com/popla69/pic/blob/main/src/pic/realworld/reporting.py): `src/pic/realworld/reporting.py`
- [Attack Scenarios](https://github.com/popla69/pic/tree/main/src/pic/realworld/testers): `src/pic/realworld/testers`

### Shared Data Models

- [Telemetry Events](https://github.com/popla69/pic/blob/main/src/pic/models/events.py): `src/pic/models/events.py`
- [Security Decisions](https://github.com/popla69/pic/blob/main/src/pic/models/decision.py): `src/pic/models/decision.py`
- [Signed Messages](https://github.com/popla69/pic/blob/main/src/pic/models/integration.py): `src/pic/models/integration.py`

### Other components

- **Application User**

## Connections

- Application User → Integrated PIC: starts monitoring (evidence: `README.md`)
- Integrated PIC → CellAgent: initializes (evidence: `src/pic/integrated.py`)
- Integrated PIC → BrainCore: initializes (evidence: `src/pic/integrated.py`)
- Integrated PIC → Brain Connector: connects (evidence: `src/pic/integrated.py`)
- Integrated PIC → Baseline State: initializes (evidence: `src/pic/integrated.py`)
- Integrated PIC → Signed Audit Log: initializes (evidence: `src/pic/integrated.py`)
- Integrated PIC → Event Traces: initializes (evidence: `src/pic/integrated.py`)
- CellAgent → Brain Connector: sends events (evidence: `src/pic/cellagent/agent.py`)
- CellAgent → PII Redaction: redacts data (evidence: `src/pic/cellagent/agent.py`)
- CellAgent → Rate Limiting: limits traffic (evidence: `src/pic/cellagent/agent.py`)
- Brain Connector → BrainCore: forwards events (evidence: `src/pic/cellagent/brain_connector.py`)
- BrainCore → Security Validation: validates signatures (evidence: `src/pic/brain/core.py`)
- BrainCore → Event Traces: stores events (evidence: `src/pic/brain/core.py`)
- BrainCore → Baseline State: reads baselines (evidence: `src/pic/brain/core.py`)
- BrainCore → Event Normalization: normalizes events (evidence: `src/pic/brain/core.py`)
- BrainCore → Anomaly Detection: detects anomalies (evidence: `src/pic/brain/core.py`)
- BrainCore → Baseline Profiling: profiles baselines (evidence: `src/pic/brain/core.py`)
- BrainCore → Pattern Cache: checks patterns (evidence: `src/pic/brain/core.py`)
- BrainCore → Action Executor: executes action (evidence: `src/pic/brain/core.py`)
- BrainCore → Signed Audit Log: logs decisions (evidence: `src/pic/brain/core.py`)
- Signed Audit Log → HMAC Crypto: signs entries (evidence: `src/pic/storage/audit_store.py`)
- BrainCore → Telemetry Events: processes events (evidence: `src/pic/brain/core.py`)
- BrainCore → Security Decisions: returns decisions (evidence: `src/pic/brain/core.py`)
- Brain Connector → Signed Messages: uses messages (evidence: `src/pic/cellagent/brain_connector.py`)
- Integrated PIC → Configuration: loads settings (evidence: `src/pic/integrated.py`)
- Test Suite → Test Harness: runs through (evidence: `src/pic/realworld/suite.py`)
- Test Suite → Safety Controls: applies controls (evidence: `src/pic/realworld/suite.py`)
- Test Suite → Sandbox: uses sandbox (evidence: `src/pic/realworld/suite.py`)
- Test Suite → Test Reporting: produces reports (evidence: `src/pic/realworld/suite.py`)
- Test Suite → Attack Scenarios: dispatches scenarios (evidence: `src/pic/realworld/suite.py`)
- Test Harness → Safety Controls: checks safety (evidence: `src/pic/realworld/harness.py`)
- Test Harness → Sandbox: uses sandbox (evidence: `src/pic/realworld/harness.py`)
- Test Harness → BrainCore: exercises engine (evidence: `src/pic/realworld/harness.py`)
- Test Harness → Baseline State: uses state (evidence: `src/pic/realworld/harness.py`)
- Test Harness → Signed Audit Log: uses audit log (evidence: `src/pic/realworld/harness.py`)
- Test Harness → Event Traces: uses traces (evidence: `src/pic/realworld/harness.py`)
