# mobarak93/securesense architecture

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

- Interactive diagram: https://gitdiagram.com/mobarak93/securesense
- Repository: https://github.com/mobarak93/securesense

## Overview

1. **Project shape**
   SecureSense is a Python-based “healthcare IoT security intelligence” agent. The repo is organized around one core agent, a threat-intel MCP service, security analysis utilities, and Terraform deployment assets.

2. **Primary runtime entrypoints**
   The `app/` package contains the main agent implementation (`agent.py`) and the runtime-facing application wrapper (`agent_runtime_app.py`). These are the central execution path for the agent when it is launched by an agent runtime or orchestration layer.

3. **Agent orchestration layer**
   The agent layer appears to own request handling, prompt/tool coordination, and response assembly. `agents-cli-manifest.yaml` suggests the project is designed to be packaged or executed through an agent CLI/runtime rather than as a generic library.

4. **Threat intelligence service boundary**
   `mcp_server/threat_intel_server.py` is a separate MCP server boundary that likely exposes threat-intel capabilities as tools/services to the agent. This separation implies the agent delegates specialized lookups or enrichment to an externalizable tool server instead of embedding all intelligence logic in-process.

5. **Security analysis subsystem**
   The `security/` package contains `input_validator.py` and `stride_analyzer.py`, which form the main defensive pipeline: validate incoming content first, then analyze it with a STRIDE-oriented security model. `security/CONTEXT.md` likely documents the security assumptions and threat-modeling context used by that pipeline.

6. **Domain/skill logic**
   `skills/real_ids_model.py` is the main domain-specific skill module. Based on the name, it likely handles identification or normalization of real-world identifiers in healthcare IoT/security-related inputs, and is a reusable capability the agent can call during analysis.

7. **Telemetry and observability**
   `app/app_utils/telemetry.py` and the Terraform telemetry assets (`deployment/terraform/shared/genai_logs_schema.json`, `telemetry.tf`, `telemetry_outputs.tf`) indicate a dedicated telemetry/logging path. The architecture includes structured generation/collection of agent logs or GenAI traces, not just application output.

8. **Infrastructure as code**
   `deployment/terraform/single-project/` contains the cloud deployment boundary: APIs, IAM, storage, service wiring, and telemetry provisioning. This repo is meant to be deployed as managed infrastructure, with clear separation between application code and cloud resources.

9. **Data flow through the system**
   The likely flow is: input arrives at the agent runtime → `input_validator` checks it → `stride_analyzer` classifies risk/threat posture → the agent calls skills and/or the MCP threat-intel server for enrichment → telemetry is emitted for audit/traceability → the response is returned to the caller.

10. **Testing and evaluation**
    The repo has three test layers: unit tests for validator, STRIDE analyzer, skill logic, and threat-intel server; integration tests for the agent and runtime app; and `tests/eval/` datasets plus config for repeatable benchmark-style evaluation. This suggests both functional correctness and agent-quality regression testing are first-class concerns.

11. **Packaging and execution context**
    `pyproject.toml` and `uv.lock` show a modern Python packaging/runtime setup. The presence of `verify_agents.py` suggests an additional conformance or validation step for agent artifacts before deployment or release.

12. **Architectural boundary summary**
    For a diagram, the main boxes are: **Agent runtime/app**, **Security layer**, **Skills/domain logic**, **MCP threat-intel server**, **Telemetry/observability**, and **Terraform-managed cloud infrastructure**. The key cross-cutting concern is that all external or high-risk inputs pass through validation and security analysis before the agent consults tools or emits telemetry.

Main entry points: [`app/agent.py`](https://github.com/mobarak93/securesense/blob/main/app/agent.py) (Agent core), [`mcp_server/threat_intel_server.py`](https://github.com/mobarak93/securesense/blob/main/mcp_server/threat_intel_server.py) (Intel server), [`deployment/terraform/single-project/telemetry.tf`](https://github.com/mobarak93/securesense/blob/main/deployment/terraform/single-project/telemetry.tf) (Telemetry stack), [`app/agent_runtime_app.py`](https://github.com/mobarak93/securesense/blob/main/app/agent_runtime_app.py) (Runtime app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_agent["Agent core<br/>python agent<br/>[agent.py]"]
  node_app_runtime["Runtime app<br/>python entrypoint"]
  node_manifest["Agent manifest<br/>runtime manifest"]
end

subgraph group_analysis["Security"]
  node_input_validator["Validator<br/>security gate<br/>[input_validator.py]"]
  node_stride_analyzer["STRIDE<br/>threat analyzer<br/>[stride_analyzer.py]"]
  node_security_context["Security context<br/>policy doc<br/>[CONTEXT.md]"]
end

subgraph group_intelligence["Threat Intel"]
  node_threat_server["Intel server<br/>mcp server"]
end

subgraph group_domain["Skills"]
  node_real_ids["ID model<br/>domain skill<br/>[real_ids_model.py]"]
end

subgraph group_observability["Telemetry"]
  node_telemetry["Telemetry<br/>observability utils<br/>[telemetry.py]"]
end

subgraph group_infra["Infra"]
  node_terraform_service["Service stack<br/>terraform module<br/>[service.tf]"]
  node_terraform_telemetry["Telemetry stack<br/>terraform module<br/>[telemetry.tf]"]
  node_genai_schema["Log schema<br/>data schema"]
  node_completions_sql["Completions SQL<br/>sql asset<br/>[completions.sql]"]
end

subgraph group_quality["Tests"]
  node_eval_data["Eval set<br/>benchmark data<br/>[basic-dataset.json]"]
  node_eval_config["Eval config<br/>benchmark config<br/>[eval_config.yaml]"]
  node_test_agent["Agent tests<br/>integration tests<br/>[test_agent.py]"]
  node_test_security["Security tests<br/>unit tests"]
  node_test_intel["Intel tests<br/>unit tests"]
  node_verify_agents["Verify agents<br/>release check<br/>[verify_agents.py]"]
end

node_manifest -->|"launches"| node_app_runtime
node_app_runtime -->|"invokes"| node_app_agent
node_app_agent -->|"validates"| node_input_validator
node_input_validator -->|"feeds"| node_stride_analyzer
node_stride_analyzer -->|"guided by"| node_security_context
node_app_agent -->|"uses"| node_real_ids
node_app_agent -->|"enriches"| node_threat_server
node_app_agent -->|"emits"| node_telemetry
node_threat_server -->|"logs"| node_telemetry
node_terraform_service -->|"deploys"| node_app_runtime
node_terraform_service -->|"provisions"| node_threat_server
node_terraform_telemetry -->|"provisions"| node_telemetry
node_terraform_telemetry -->|"uses"| node_genai_schema
node_terraform_telemetry -->|"includes"| node_completions_sql
node_test_agent -->|"covers"| node_app_agent
node_test_security -->|"covers"| node_input_validator
node_test_security -->|"covers"| node_stride_analyzer
node_test_intel -->|"covers"| node_threat_server
node_eval_data -->|"drives"| node_eval_config
node_verify_agents -->|"checks"| node_manifest

click node_app_agent "https://github.com/mobarak93/securesense/blob/main/app/agent.py"
click node_app_runtime "https://github.com/mobarak93/securesense/blob/main/app/agent_runtime_app.py"
click node_telemetry "https://github.com/mobarak93/securesense/blob/main/app/app_utils/telemetry.py"
click node_input_validator "https://github.com/mobarak93/securesense/blob/main/security/input_validator.py"
click node_stride_analyzer "https://github.com/mobarak93/securesense/blob/main/security/stride_analyzer.py"
click node_security_context "https://github.com/mobarak93/securesense/blob/main/security/CONTEXT.md"
click node_threat_server "https://github.com/mobarak93/securesense/blob/main/mcp_server/threat_intel_server.py"
click node_real_ids "https://github.com/mobarak93/securesense/blob/main/skills/real_ids_model.py"
click node_terraform_service "https://github.com/mobarak93/securesense/blob/main/deployment/terraform/single-project/service.tf"
click node_terraform_telemetry "https://github.com/mobarak93/securesense/blob/main/deployment/terraform/single-project/telemetry.tf"
click node_genai_schema "https://github.com/mobarak93/securesense/blob/main/deployment/terraform/shared/genai_logs_schema.json"
click node_completions_sql "https://github.com/mobarak93/securesense/blob/main/deployment/terraform/shared/completions.sql"
click node_eval_data "https://github.com/mobarak93/securesense/blob/main/tests/eval/datasets/basic-dataset.json"
click node_eval_config "https://github.com/mobarak93/securesense/blob/main/tests/eval/eval_config.yaml"
click node_test_agent "https://github.com/mobarak93/securesense/blob/main/tests/integration/test_agent.py"
click node_test_security "https://github.com/mobarak93/securesense/blob/main/tests/unit/test_input_validator.py"
click node_test_intel "https://github.com/mobarak93/securesense/blob/main/tests/unit/test_threat_intel_server.py"
click node_verify_agents "https://github.com/mobarak93/securesense/blob/main/verify_agents.py"
click node_manifest "https://github.com/mobarak93/securesense/blob/main/agents-cli-manifest.yaml"

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_app_agent,node_app_runtime,node_manifest,node_eval_data,node_eval_config,node_test_agent,node_test_security,node_test_intel,node_verify_agents toneBlue
class node_input_validator,node_stride_analyzer,node_security_context toneAmber
class node_threat_server toneMint
class node_real_ids toneRose
class node_telemetry toneIndigo
class node_terraform_service,node_terraform_telemetry,node_genai_schema,node_completions_sql toneTeal
```

## Components

### Runtime

Agent execution and app-facing entrypoints

- [Agent core](https://github.com/mobarak93/securesense/blob/main/app/agent.py): python agent · Main orchestration and request handling logic · `app/agent.py`
- [Runtime app](https://github.com/mobarak93/securesense/blob/main/app/agent_runtime_app.py): python entrypoint · Runtime-facing wrapper for launching the agent · `app/agent_runtime_app.py`
- [Agent manifest](https://github.com/mobarak93/securesense/blob/main/agents-cli-manifest.yaml): runtime manifest · CLI/runtime packaging and execution descriptor · `agents-cli-manifest.yaml`

### Security

Input defense and threat analysis

- [Validator](https://github.com/mobarak93/securesense/blob/main/security/input_validator.py): security gate · Validates inbound content before analysis · `security/input_validator.py`
- [STRIDE](https://github.com/mobarak93/securesense/blob/main/security/stride_analyzer.py): threat analyzer · Applies STRIDE-oriented security analysis · `security/stride_analyzer.py`
- [Security context](https://github.com/mobarak93/securesense/blob/main/security/CONTEXT.md): policy doc · Threat-model and security assumptions for analysis · `security/CONTEXT.md`

### Threat Intel

Externalizable enrichment service boundary

- [Intel server](https://github.com/mobarak93/securesense/blob/main/mcp_server/threat_intel_server.py): mcp server · Threat-intel MCP boundary exposed to the agent · `mcp_server/threat_intel_server.py`

### Skills

Domain-specific reusable logic

- [ID model](https://github.com/mobarak93/securesense/blob/main/skills/real_ids_model.py): domain skill · Real-world identifier handling and normalization · `skills/real_ids_model.py`

### Telemetry

Logging and trace emission

- [Telemetry](https://github.com/mobarak93/securesense/blob/main/app/app_utils/telemetry.py): observability utils · Structured logging and trace emission helpers · `app/app_utils/telemetry.py`

### Infra

Terraform deployment and cloud wiring

- [Service stack](https://github.com/mobarak93/securesense/blob/main/deployment/terraform/single-project/service.tf): terraform module · Cloud service wiring, APIs, IAM, and storage · `deployment/terraform/single-project/service.tf`
- [Telemetry stack](https://github.com/mobarak93/securesense/blob/main/deployment/terraform/single-project/telemetry.tf): terraform module · Infrastructure for logs and telemetry provisioning · `deployment/terraform/single-project/telemetry.tf`
- [Log schema](https://github.com/mobarak93/securesense/blob/main/deployment/terraform/shared/genai_logs_schema.json): data schema · Structured schema for GenAI log records · `deployment/terraform/shared/genai_logs_schema.json`
- [Completions SQL](https://github.com/mobarak93/securesense/blob/main/deployment/terraform/shared/completions.sql): sql asset · Shared completion/query asset used by deployment · `deployment/terraform/shared/completions.sql`

### Tests

Unit, integration, and evaluation coverage

- [Eval set](https://github.com/mobarak93/securesense/blob/main/tests/eval/datasets/basic-dataset.json): benchmark data · Repeatable evaluation dataset and config · `tests/eval/datasets/basic-dataset.json`
- [Eval config](https://github.com/mobarak93/securesense/blob/main/tests/eval/eval_config.yaml): benchmark config · Evaluation harness settings for dataset runs · `tests/eval/eval_config.yaml`
- [Agent tests](https://github.com/mobarak93/securesense/blob/main/tests/integration/test_agent.py): integration tests · Integration coverage for agent and runtime app · `tests/integration/test_agent.py`
- [Security tests](https://github.com/mobarak93/securesense/blob/main/tests/unit/test_input_validator.py): unit tests · Unit coverage for validator and STRIDE analysis · `tests/unit/test_input_validator.py`
- [Intel tests](https://github.com/mobarak93/securesense/blob/main/tests/unit/test_threat_intel_server.py): unit tests · Unit coverage for threat-intel server behavior · `tests/unit/test_threat_intel_server.py`
- [Verify agents](https://github.com/mobarak93/securesense/blob/main/verify_agents.py): release check · Validation step for agent artifacts before deployment · `verify_agents.py`

## Connections

- Agent manifest → Runtime app: launches · Defines how the agent runtime starts the app
- Runtime app → Agent core: invokes · Wrapper initializes and delegates to core agent
- Agent core → Validator: validates · Inbound content is checked before deeper processing
- Validator → STRIDE: feeds · Validated input is passed into threat analysis
- STRIDE → Security context: guided by · Security assumptions inform the analysis model
- Agent core → ID model: uses · Agent consults domain-specific identifier logic
- Agent core → Intel server: enriches · Agent delegates specialized threat-intel lookups
- Agent core → Telemetry: emits · Operational traces and logs are recorded
- Intel server → Telemetry: logs · MCP service activity contributes to observability
- Service stack → Runtime app: deploys · Cloud service infrastructure hosts the runtime
- Service stack → Intel server: provisions · Deployment includes the external tool/service boundary
- Telemetry stack → Telemetry: provisions · Telemetry infrastructure supports log capture
- Telemetry stack → Log schema: uses · Structured logging schema defines emitted records
- Telemetry stack → Completions SQL: includes · Shared SQL asset supports telemetry/completion plumbing
- Agent tests → Agent core: covers · Integration tests validate the agent flow
- Security tests → Validator: covers · Unit tests verify validation and analysis logic
- Security tests → STRIDE: covers · Unit tests verify STRIDE classification behavior
- Intel tests → Intel server: covers · Unit tests verify MCP threat-intel behavior
- Eval set → Eval config: drives · Dataset is consumed by the evaluation configuration
- Verify agents → Agent manifest: checks · Release validation confirms agent artifact integrity