# anandprafull/fedsecureai architecture

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

- Interactive diagram: https://gitdiagram.com/anandprafull/fedsecureai
- Repository: https://github.com/anandprafull/fedsecureai

## Overview

1. **Overall shape**
   - FedSecureAI is a federated intrusion-detection system with three training clients—**Army, Navy, Air Force**—and a central **Flower-based aggregator**.
   - The repo is split into three main boundaries: a **Python FL backend**, a **training dashboard** (`dashboard/`), and a **SOC/security console** (`soc-dashboard/`).

2. **Data ingestion and preprocessing**
   - The raw input is the **CIC-IDS2017** CSV dataset placed under `data/raw/`.
   - `src/data_processor.py` turns those raw files into **partitioned, non-IID client datasets** stored in `data/partitions/`, which is the handoff point from offline preprocessing into federated training.

3. **Federated training runtime**
   - `src/server.py` runs the **central federated server**.
   - `src/client.py` runs the **local training nodes** for each compartmented domain.
   - The clients train locally on their partition and exchange model updates with the server; the server aggregates those updates into a global model.

4. **Model and training logic**
   - `src/model.py` defines the PyTorch intrusion-detection network used by both server-side evaluation and client-side training.
   - `src/strategy.py` contains the aggregation policy, including the repo’s main defense mechanism: **coordinate-wise median** aggregation.
   - The README also indicates **FedProx** is used to stabilize training under strong non-IID splits.

5. **Adversarial and security simulation**
   - `src/attack_sim.py` models a **gradient-flipping / red-teaming attack** so the FL loop can be tested under malicious client behavior.
   - This is part of the security boundary around training rather than a separate product feature: it exists to stress the aggregation logic and produce security telemetry.

6. **Persistence and audit artifacts**
   - Training outputs are persisted to `logs/` and `saved_models/`.
   - Key artifacts include the latest global model, per-node local checkpoints, and training logs; these are the main data source for both dashboards and offline evaluation.
   - This persistence layer is important because the UI components appear to consume files rather than live model objects.

7. **Explainability pipeline**
   - `src/explainability.py` generates **SHAP-based** feature attribution for the trained global model.
   - The README says the generated outputs are written back into `logs/` as images and metadata, making explainability an offline artifact-generation step that the dashboard can trigger and display.

8. **Training dashboard**
   - `dashboard/` is a separate **Next.js** app for monitoring the FL training lifecycle.
   - Its API routes suggest three functions: serving dashboard data, exposing artifacts by name, and triggering explainability generation.
   - Conceptually, it is a read/trigger layer over the persisted training and explainability artifacts, not the training engine itself.

9. **SOC dashboard**
   - `soc-dashboard/` is a second **Next.js** app dedicated to security operations.
   - It has routes for SOC event data and report generation, and a `lib/soc-data.ts` helper that likely centralizes event parsing/analysis.
   - This console is the incident-response boundary: it focuses on attack events, drift, node risk, and report output rather than training metrics.

10. **Evaluation and validation**
   - `src/evaluate_saved_models.py` compares the persisted global checkpoint against the three local checkpoints using held-out partition data and reports classification metrics.
   - Tests in `tests/` cover the data processor and aggregation strategy, which are the two most architecture-sensitive Python subsystems.

11. **Configuration and deployment**
   - `config.yaml` centralizes runtime settings for the server, training, FedProx, aggregation, saved-model paths, and attack parameters.
   - Deployment is containerized with separate Dockerfiles for **client**, **server**, and the two dashboards, orchestrated by `docker-compose.yml`.
   - This reinforces the repo’s main architectural separation: backend FL runtime plus two independent frontend consoles.

12. **Primary end-to-end flow**
   - Raw dataset → preprocessing/partitioning → local client training → server aggregation → persisted checkpoints/logs → dashboard and SOC visualization/reporting.
   - The only major cross-cutting dependencies are the shared filesystem artifacts in `logs/` and `saved_models/`, which act as the integration contract between training, explainability, evaluation, and the UI layers.

Main entry points: [`src/server.py`](https://github.com/anandprafull/fedsecureai/blob/main/src/server.py) (Server), [`src/client.py`](https://github.com/anandprafull/fedsecureai/blob/main/src/client.py) (Client), [`logs`](https://github.com/anandprafull/fedsecureai/tree/main/logs) (Logs), [`dashboard/app/api`](https://github.com/anandprafull/fedsecureai/tree/main/dashboard/app/api) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_backend["Python FL backend"]
  node_data_processor["Data prep<br/>partitioning<br/>[data_processor.py]"]
  node_server(("Server<br/>Flower aggregator<br/>[server.py]"))
  node_client(("Client<br/>FL trainer<br/>[client.py]"))
  node_model["Model<br/>PyTorch IDS<br/>[model.py]"]
  node_strategy["Aggregation<br/>median + FedProx<br/>[strategy.py]"]
  node_attack_sim{{"Attack sim<br/>gradient flipping<br/>[attack_sim.py]"}}
  node_explainability["Explainability<br/>SHAP pipeline<br/>[explainability.py]"]
  node_evaluate_saved_models["Evaluation<br/>checkpoint scoring"]
end

subgraph group_training_dashboard["Training dashboard"]
  node_dashboard_api["Dashboard API<br/>Next.js routes"]
  node_dashboard_ui["Training UI<br/>Next.js app<br/>[page.tsx]"]
end

subgraph group_soc_dashboard["SOC dashboard"]
  node_soc_api["SOC API<br/>Next.js routes"]
  node_soc_ui["SOC UI<br/>Next.js app<br/>[page.tsx]"]
  node_soc_data["SOC data<br/>event analysis<br/>[soc-data.ts]"]
end

subgraph group_shared_artifacts["Shared artifacts"]
  node_raw_data[("Raw data<br/>CIC-IDS2017 CSV")]
  node_partitions[("Partitions<br/>non-IID client data")]
  node_logs[("Logs<br/>artifacts store")]
  node_models[("Saved models<br/>checkpoints")]
end

node_raw_data -->|"ingest"| node_data_processor
node_data_processor -->|"write"| node_partitions
node_partitions -->|"train on"| node_client
node_client -->|"update"| node_server
node_server -->|"aggregate with"| node_strategy
node_strategy -->|"combine"| node_model
node_client -->|"fit"| node_model
node_server -->|"evaluate"| node_model
node_attack_sim -.->|"poison"| node_client
node_attack_sim -.->|"stress"| node_strategy
node_server -->|"emit"| node_logs
node_server -->|"save"| node_models
node_explainability -->|"write"| node_logs
node_models -->|"load"| node_evaluate_saved_models
node_partitions -->|"test on"| node_evaluate_saved_models
node_logs -->|"serve"| node_dashboard_api
node_models -->|"serve"| node_dashboard_api
node_dashboard_api -->|"feed"| node_dashboard_ui
node_explainability -->|"trigger"| node_dashboard_api
node_logs -->|"serve"| node_soc_api
node_soc_data -->|"support"| node_soc_api
node_soc_api -->|"feed"| node_soc_ui
node_server -.->|"emit telemetry"| node_soc_api

click node_raw_data "https://github.com/anandprafull/fedsecureai/tree/main/data/raw"
click node_partitions "https://github.com/anandprafull/fedsecureai/tree/main/data/partitions"
click node_logs "https://github.com/anandprafull/fedsecureai/tree/main/logs"
click node_models "https://github.com/anandprafull/fedsecureai/tree/main/saved_models"
click node_data_processor "https://github.com/anandprafull/fedsecureai/blob/main/src/data_processor.py"
click node_server "https://github.com/anandprafull/fedsecureai/blob/main/src/server.py"
click node_client "https://github.com/anandprafull/fedsecureai/blob/main/src/client.py"
click node_model "https://github.com/anandprafull/fedsecureai/blob/main/src/model.py"
click node_strategy "https://github.com/anandprafull/fedsecureai/blob/main/src/strategy.py"
click node_attack_sim "https://github.com/anandprafull/fedsecureai/blob/main/src/attack_sim.py"
click node_explainability "https://github.com/anandprafull/fedsecureai/blob/main/src/explainability.py"
click node_evaluate_saved_models "https://github.com/anandprafull/fedsecureai/blob/main/src/evaluate_saved_models.py"
click node_dashboard_api "https://github.com/anandprafull/fedsecureai/tree/main/dashboard/app/api"
click node_dashboard_ui "https://github.com/anandprafull/fedsecureai/blob/main/dashboard/app/page.tsx"
click node_soc_api "https://github.com/anandprafull/fedsecureai/tree/main/soc-dashboard/app/api"
click node_soc_ui "https://github.com/anandprafull/fedsecureai/blob/main/soc-dashboard/app/page.tsx"
click node_soc_data "https://github.com/anandprafull/fedsecureai/blob/main/soc-dashboard/lib/soc-data.ts"

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_data_processor,node_server,node_client,node_model,node_strategy,node_attack_sim,node_explainability,node_evaluate_saved_models toneBlue
class node_dashboard_api,node_dashboard_ui toneAmber
class node_soc_api,node_soc_ui,node_soc_data toneMint
class node_raw_data,node_partitions,node_logs,node_models toneRose
```

## Components

### Python FL backend

Federated learning runtime, model logic, security simulation, and offline evaluation.

- [Data prep](https://github.com/anandprafull/fedsecureai/blob/main/src/data_processor.py): partitioning · Transforms raw CSV input into partitioned non-IID client datasets. · `src/data_processor.py`
- [Server](https://github.com/anandprafull/fedsecureai/blob/main/src/server.py): Flower aggregator · Central federated server that coordinates rounds and aggregates client updates. · `src/server.py`
- [Client](https://github.com/anandprafull/fedsecureai/blob/main/src/client.py): FL trainer · Local training node used by each compartmented client domain. · `src/client.py`
- [Model](https://github.com/anandprafull/fedsecureai/blob/main/src/model.py): PyTorch IDS · Intrusion-detection network shared by client training and server-side evaluation. · `src/model.py`
- [Aggregation](https://github.com/anandprafull/fedsecureai/blob/main/src/strategy.py): median + FedProx · Aggregation policy centered on coordinate-wise median with FedProx stabilization. · `src/strategy.py`
- [Attack sim](https://github.com/anandprafull/fedsecureai/blob/main/src/attack_sim.py): gradient flipping · Red-team simulation of malicious client updates to stress the federation. · `src/attack_sim.py`
- [Explainability](https://github.com/anandprafull/fedsecureai/blob/main/src/explainability.py): SHAP pipeline · Generates feature attribution artifacts for the trained global model. · `src/explainability.py`
- [Evaluation](https://github.com/anandprafull/fedsecureai/blob/main/src/evaluate_saved_models.py): checkpoint scoring · Compares persisted global and local checkpoints against held-out partition data. · `src/evaluate_saved_models.py`

### Training dashboard

Next.js app for monitoring training and explainability artifacts.

- [Dashboard API](https://github.com/anandprafull/fedsecureai/tree/main/dashboard/app/api): Next.js routes · Serves dashboard data, artifact access, and explainability triggers. · `dashboard/app/api`
- [Training UI](https://github.com/anandprafull/fedsecureai/blob/main/dashboard/app/page.tsx): Next.js app · Operator console for monitoring federated training and artifacts. · `dashboard/app/page.tsx`

### SOC dashboard

Next.js app for security operations, events, and reports.

- [SOC API](https://github.com/anandprafull/fedsecureai/tree/main/soc-dashboard/app/api): Next.js routes · Serves SOC event data and report generation endpoints. · `soc-dashboard/app/api`
- [SOC UI](https://github.com/anandprafull/fedsecureai/blob/main/soc-dashboard/app/page.tsx): Next.js app · Security operations console for incidents, risk, and reports. · `soc-dashboard/app/page.tsx`
- [SOC data](https://github.com/anandprafull/fedsecureai/blob/main/soc-dashboard/lib/soc-data.ts): event analysis · Helper layer for SOC event parsing and analysis. · `soc-dashboard/lib/soc-data.ts`

### Shared artifacts

Filesystem boundary for datasets, checkpoints, logs, and generated outputs.

- [Raw data](https://github.com/anandprafull/fedsecureai/tree/main/data/raw): CIC-IDS2017 CSV · Source intrusion dataset placed under data/raw/ for offline preprocessing. · `data/raw`
- [Partitions](https://github.com/anandprafull/fedsecureai/tree/main/data/partitions): non-IID client data · Partitioned training datasets for the federated clients. · `data/partitions`
- [Logs](https://github.com/anandprafull/fedsecureai/tree/main/logs): artifacts store · Training metrics, explainability outputs, and audit artifacts consumed by UIs and evaluation. · `logs`
- [Saved models](https://github.com/anandprafull/fedsecureai/tree/main/saved_models): checkpoints · Persisted global and local model checkpoints used by dashboards and evaluation. · `saved_models`

## Connections

- Raw data → Data prep: ingest · Offline preprocessing reads raw CIC-IDS2017 CSV files.
- Data prep → Partitions: write · Produces partitioned non-IID client datasets.
- Partitions → Client: train on · Each client trains locally on its assigned partition.
- Client → Server: update · Clients send local model updates to the federated server.
- Server → Aggregation: aggregate with · Server applies the aggregation policy each round.
- Aggregation → Model: combine · Aggregation operates over model updates and weights.
- Client → Model: fit · Clients train the shared PyTorch intrusion-detection network.
- Server → Model: evaluate · Server-side evaluation uses the shared model definition.
- Attack sim → Client: poison · Simulated malicious behavior targets client updates during training.
- Attack sim → Aggregation: stress · Attack simulation is used to test robustness of aggregation.
- Server → Logs: emit · Training metrics and security telemetry are persisted as artifacts.
- Server → Saved models: save · Global checkpoints and selected local checkpoints are persisted.
- Explainability → Logs: write · SHAP outputs and metadata are stored for later display.
- Saved models → Evaluation: load · Evaluation consumes persisted checkpoints.
- Partitions → Evaluation: test on · Held-out partition data is used for checkpoint comparison.
- Logs → Dashboard API: serve · Dashboard reads metrics, artifacts, and explainability outputs from files.
- Saved models → Dashboard API: serve · Dashboard exposes model artifacts by name.
- Dashboard API → Training UI: feed · API routes back the training dashboard interface.
- Explainability → Dashboard API: trigger · Dashboard can initiate explainability generation.
- Logs → SOC API: serve · SOC console reads events, reports, and security artifacts from persisted outputs.
- SOC data → SOC API: support · SOC helper centralizes parsing and analysis for API responses.
- SOC API → SOC UI: feed · API routes back the SOC console interface.
- Server → SOC API: emit telemetry · Training and attack telemetry can surface in the SOC boundary.