# ogunsolaolalekanoo-dev/behavioral-anomaly-detection architecture

> Architecture diagram of the GitHub repository ogunsolaolalekanoo-dev/behavioral-anomaly-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection
- Repository: https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection

## Overview

This repository implements behavioral anomaly detection for authentication events. The documented workflow generates synthetic login events, derives per-user behavioral baselines and deviation features, trains Isolation Forest and autoencoder detectors, then serves real-time risk scores and risk-adaptive authentication decisions through FastAPI. Evaluation and anomaly-distribution plots are also part of the detector capability. The API and training code show the principal calls and artifact handoffs; generated data and model files are runtime artifacts, not files present in the supplied tree.

Main entry points: [`src/api.py`](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py) (Scoring API), [`src/detector.py`](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py) (Model Training), [`src/features.py`](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/features.py) (Feature Engineering), [`src/simulator.py`](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/simulator.py) (Event Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Event Simulation"]
  node_simulator["Event Simulator<br/>[simulator.py]"]
  node_event_data[("Auth Event Data")]
end

subgraph group_features["Behavioral Features"]
  node_feature_engine["Feature Engineering<br/>[features.py]"]
  node_baseline_data[("User Baselines")]
  node_feature_data[("Feature Data")]
end

subgraph group_detection["Detection Models"]
  node_model_training["Model Training<br/>[detector.py]"]
  node_detector_models[("Trained Models")]
  node_model_evaluation["Model Evaluation<br/>[detector.py]"]
end

subgraph group_scoring["Risk Scoring"]
  node_score_api["Scoring API<br/>[api.py]"]
  node_request_features["Request Features<br/>[api.py]"]
  node_risk_ensemble["Anomaly Scoring<br/>[detector.py]"]
  node_auth_decision["Risk Decision<br/>[api.py]"]
  node_score_response["Risk Response<br/>[api.py]"]
end

node_client(("Auth Client"))

node_simulator -->|"writes events"| node_event_data
node_event_data -->|"loads events"| node_feature_engine
node_feature_engine -->|"writes baselines"| node_baseline_data
node_feature_engine -->|"writes features"| node_feature_data
node_event_data -->|"loads events"| node_model_training
node_model_training -->|"calls build_features"| node_feature_engine
node_model_training -->|"saves models"| node_detector_models
node_model_training -->|"evaluates scores"| node_model_evaluation
node_model_evaluation -->|"plots results"| node_detector_models
node_client -->|"submits event"| node_score_api
node_score_api -->|"loads models"| node_detector_models
node_score_api -->|"loads baselines"| node_baseline_data
node_score_api -->|"prepares event"| node_request_features
node_request_features -->|"requests scores"| node_risk_ensemble
node_risk_ensemble -->|"scores with"| node_detector_models
node_score_api -->|"assigns tier"| node_auth_decision
node_score_api -->|"returns result"| node_score_response

click node_simulator "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/simulator.py"
click node_feature_engine "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/features.py"
click node_model_training "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py"
click node_model_evaluation "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py"
click node_score_api "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py"
click node_request_features "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py"
click node_risk_ensemble "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py"
click node_auth_decision "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py"
click node_score_response "https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py"

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_simulator,node_event_data,node_client toneBlue
class node_feature_engine,node_baseline_data,node_feature_data toneAmber
class node_model_training,node_detector_models,node_model_evaluation toneMint
class node_score_api,node_request_features,node_risk_ensemble,node_auth_decision,node_score_response toneRose
```

## Components

### Event Simulation

- [Event Simulator](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/simulator.py): `src/simulator.py`
- **Auth Event Data**

### Behavioral Features

- [Feature Engineering](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/features.py): `src/features.py`
- **User Baselines**
- **Feature Data**

### Detection Models

- [Model Training](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py): `src/detector.py`
- **Trained Models**
- [Model Evaluation](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py): `src/detector.py`

### Risk Scoring

- [Scoring API](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py): `src/api.py`
- [Request Features](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py): `src/api.py`
- [Anomaly Scoring](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/detector.py): `src/detector.py`
- [Risk Decision](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py): `src/api.py`
- [Risk Response](https://github.com/ogunsolaolalekanoo-dev/behavioral-anomaly-detection/blob/main/src/api.py): `src/api.py`

### Other components

- **Auth Client**

## Connections

- Event Simulator → Auth Event Data: writes events (evidence: `src/simulator.py`)
- Auth Event Data → Feature Engineering: loads events (evidence: `src/features.py`)
- Feature Engineering → User Baselines: writes baselines (evidence: `src/features.py`)
- Feature Engineering → Feature Data: writes features (evidence: `src/features.py`)
- Auth Event Data → Model Training: loads events (evidence: `src/detector.py`)
- Model Training → Feature Engineering: calls build_features (evidence: `src/detector.py`)
- Model Training → Trained Models: saves models (evidence: `src/detector.py`)
- Model Training → Model Evaluation: evaluates scores (evidence: `src/detector.py`)
- Model Evaluation → Trained Models: plots results (evidence: `src/detector.py`)
- Auth Client → Scoring API: submits event (evidence: `README.md`)
- Scoring API → Trained Models: loads models (evidence: `src/api.py`)
- Scoring API → User Baselines: loads baselines (evidence: `src/api.py`)
- Scoring API → Request Features: prepares event (evidence: `src/api.py`)
- Request Features → Anomaly Scoring: requests scores (evidence: `src/api.py`)
- Anomaly Scoring → Trained Models: scores with (evidence: `src/detector.py`)
- Scoring API → Risk Decision: assigns tier (evidence: `src/api.py`)
- Scoring API → Risk Response: returns result (evidence: `src/api.py`)
