# akramiot/dcats architecture

> Architecture diagram of the GitHub repository akramiot/dcats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akramiot/dcats
- Repository: https://github.com/akramiot/dcats

## Overview

##### Project type and purpose
- This is a Python library implementing the “Dual-Layer Cognitive Architecture for Trustworthy and Secure AI Systems.”
- It is effectively a middleware/SDK that wraps an AI reasoning engine (the Core layer) with a cognitive firewall (the Oversight layer).
- Users import `DualLayerAI` from `src/dcats.py` to feed queries, get “filtered” outputs, and automatically enforce trust/security policies.

##### File structure
- Top-level directories:
– src/core: Core Reasoning Layer
– src/oversight: Four oversight modules
– src/policies: Policy store and management
– src/utils: Cross-cutting utilities (e.g., audit logging)
– examples: Starter scripts demonstrating usage
– tests: Unit tests
- Configuration: requirements.txt for dependencies, .gitignore, LICENSE, README.md.
- No external microservices or databases—policy store is in-memory or file-based and audit logs are written via utils.

##### Extract architectural insights from the README
- Two main logical layers:
1. Core Reasoning Layer (“C”)
2. Oversight Layer (“O”) with subcomponents: Attention Filter, Trust Scorer, Memory Partitioner, Output Veto
- A Policy Store feeds the oversight rules.
- An Audit Logger records events (via utils).
- The client calls `DualLayerAI.process(input)`, which orchestrates the layers.

a. Main components
1. Client Application (could be example scripts or any user code)
2. DualLayerAI Facade (entrypoint in src/dcats.py)
4. Oversight Layer container, subdivided into four modules:
– Attention Filter
– Trust Scorer
– Memory Partitioner
– Output Veto
5. Policy Store (in policies)
6. Audit Logger (in utils)
7. Optional: External AI service (if Core uses an external LLM)
b. Relationships & data flow
2. DualLayerAI → (1) Core Reasoning → core response
3. Core response → Oversight Layer (chain through the four modules)
4. Oversight modules consult Policy Store for rules
5. Oversight modules call Audit Logger on key events
6. Final approved response → DualLayerAI → Client
c. Architectural patterns & principles
– Layered architecture (clear separation of concerns)
– Single-responsibility for each oversight subcomponent
– Policy-driven control (Policy Store is the single source of truth)
– Pluggable/extensible: users can extend or swap out oversight modules or policies
d. Key technologies & frameworks
– Python 3.x
– Logging (via utils/audit_logger.py)
– Policy store (in-memory or file-based, in src/policies/policy_store.py)
– Unit tests (pytest style, in tests/)

##### Diagramming conventions
– Use rectangles for modules/layers.
- Core layer = blue
- Oversight subcomponents = orange
- Policy Store = green
- Audit Logger = gray
- Client/Examples = light yellow

##### Putting it all together
– DualLayerAI Facade at the left
- Optional annotation: “Examples/basic_usage.py” calls this flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ClientApp["Client Application"]:::client
    subgraph "DCATS Library"
        Facade["DualLayerAI Facade"]:::facade
        Core["Core Reasoning Layer"]:::core
        subgraph "Oversight Layer"
            AF["Attention Filter"]:::oversight
            TS["Trust Scorer"]:::oversight
            MP["Memory Partitioner"]:::oversight
            OV["Output Veto"]:::oversight
        end
        Policy["Policy Store"]:::policy
        Audit["Audit Logger"]:::audit
    end

    ClientApp -->|"user query"| Facade
    Facade -->|"invoke Core.process()"| Core
    Core -->|"raw AI response"| AF
    AF -->|"filtered response"| TS
    TS -->|"scored output"| MP
    MP -->|"partitioned data"| OV
    OV -->|"final response"| Facade
    AF -->|"policy lookup"| Policy
    TS -->|"policy lookup"| Policy
    MP -->|"policy lookup"| Policy
    OV -->|"policy lookup"| Policy
    AF -->|"log event"| Audit
    TS -->|"log event"| Audit
    MP -->|"log event"| Audit
    OV -->|"log event"| Audit
    Facade -->|"final output"| ClientApp

    click ClientApp "https://github.com/akramiot/dcats/blob/main/examples/basic_usage.py"
    click ClientApp "https://github.com/akramiot/dcats/blob/main/examples/secure_data_assistant.py"
    click Facade "https://github.com/akramiot/dcats/blob/main/src/dcats.py"
    click Core "https://github.com/akramiot/dcats/blob/main/src/core/reasoning_layer.py"
    click AF "https://github.com/akramiot/dcats/blob/main/src/oversight/attention_filter.py"
    click TS "https://github.com/akramiot/dcats/blob/main/src/oversight/trust_scorer.py"
    click MP "https://github.com/akramiot/dcats/blob/main/src/oversight/memory_partitioner.py"
    click OV "https://github.com/akramiot/dcats/blob/main/src/oversight/output_veto.py"
    click Policy "https://github.com/akramiot/dcats/blob/main/src/policies/policy_store.py"
    click Audit "https://github.com/akramiot/dcats/blob/main/src/utils/audit_logger.py"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef oversight fill:#FFA500,stroke:#000,stroke-width:1px
    classDef policy fill:#90EE90,stroke:#000,stroke-width:1px
    classDef audit fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef client fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef facade fill:#E6E6FA,stroke:#000,stroke-width:1px
```
