# System Architecture

The Intent-Aware Security System is structured as a robust middleware layer positioned between the client interfaces and the core identity database. It operates on a microservice-inspired architecture using a centralized API gateway.

## High-Level Topology

The system comprises three primary zones: the Frontend Client Layer, the Security Middleware (API Gateway), and the Data/Model persistence layer.

### 1. Security Middleware (Backend)
The core of the system is a high-performance, asynchronous REST API built using the FastAPI framework (`app.py`). It acts as a reverse proxy/validation gate for all incoming authentication requests. 
- **Concurrency:** Utilizes `asyncio` and `uvicorn` to handle high-throughput request validation without blocking the main event loop.
- **State Management:** Maintains a thread-safe, in-memory `ChallengeStore` for cryptographic nonces, utilizing mutex locks (`threading.Lock`) to prevent race conditions during rapid authentication attempts.
- **Pipeline:** Requests pass sequentially through two filters: the Cryptographic Verify Layer (ZKP) and the Behavioral Analysis Layer (ML). Failure at any layer results in an immediate `HTTP 403 Forbidden` rejection.

### 2. Frontend Client Layer
The client layer consists of isolated static modules served by the backend:
- **Government Portal (`static/portal/`)**: Simulates a standard citizen-facing web application. Employs a dedicated WebCrypto API JavaScript client (`zkp-client.js`) and a background web worker (`timer-worker.js`) to generate ECDSA signatures securely within the local browser context.
- **Hacker Console (`static/hacker/`)**: An interactive command-line interface simulation for launching configurable automated attacks (brute force, scraping).
- **Monitoring Dashboard (`static/dashboard/`)**: A real-time telemetry interface employing `Chart.js` for data visualization. It actively polls the API gateway to construct instantaneous visual representations of traffic volume, anomaly scatter plots, and threat assessments.
- **Architecture Comparison (`static/compare/`)**: An analytical User Interface that contrasts the vulnerabilities of legacy OTP infrastructure against the deterministic security of the ZKP implementation, specifically modeling SS7/SIM-swapping scenarios.

### 3. Data and Persistence
- **Synthetic Traffic Logs (`data/traffic_logs.csv`)**: Generated prior to execution by `generate_data.py`, comprising randomized behavioral records spanning standard traffic and attack vectors.
- **Pre-Trained ML Model (`data/model.pkl`)**: The serialized Isolation Forest model, generated by `train_model.py`, loaded into memory upon initialization of the API gateway.

## Sequence of Operations

1. **Initialization:** The API Gateway starts and loads the `model.pkl` file into RAM. It initiates a background asynchronous task to periodically prune expired cryptographic challenges.
2. **Registration:** During the first access, the client generates an ECDSA keypair locally and registers the public key with the backend (`/zkp/register`). The private key is strictly confined to local browser storage.
3. **Authentication Handshake:**
    - The client requests a challenge nonce from the backend.
    - The client signs the traffic payload parameters and the designated nonce using its private key.
    - The bundled request (Data + Signature + Challenge) is transmitted to the gateway.
4. **Validation:**
    - **Layer 1:** The gateway verifies the signature mathematical integrity using the user's stored public key and instantly expires the challenge nonce to preclude replay attacks.
    - **Layer 2:** The traffic parameters (Rate, Time, Location, Payload size) are passed to the `IsolationForest` predicting agent.
    - An authorization decision (`ALLOWED` or `BLOCKED`) is computed, logged to the central telemetry queue, and returned to the client.