# gnanadhivya/behaviorlock architecture

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

- Interactive diagram: https://gitdiagram.com/gnanadhivya/behaviorlock
- Repository: https://github.com/gnanadhivya/behaviorlock

## Overview

BehaviorLock provides continuous, privacy-preserving web authentication: the browser summarizes behavior into short feature windows, the backend evaluates risk, and the user receives security-state updates and account/device dashboards. Authentication and device recognition establish the session; monitoring feeds the risk-scoring and state-transition stages, with re-authentication for high risk. README documentation describes the backend-to-ML-service and database architecture; sampled source confirms several service/repository calls. Other routes and some wiring are represented only at subsystem level because their source was not sampled.

Main entry points: [`backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java`](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java) (Security state machine), [`backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java`](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java) (Security endpoints), [`backend/src/main/java/com/behaviorlock/backend/service/AuthService.java`](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/AuthService.java) (Authentication), [`frontend/src/context/AuthContext.jsx`](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/context/AuthContext.jsx) (Auth context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routes<br/>[App.jsx]"]
  node_authctx["Auth context<br/>[AuthContext.jsx]"]
  node_collector["Behavior collector"]
  node_behaviorclient["Behavior API client<br/>[behaviorService.js]"]
  node_apiclient["REST client<br/>[api.js]"]
end

subgraph group_identity["Identity and devices"]
  node_authservice["Authentication<br/>[AuthService.java]"]
  node_deviceservice["Device and session service<br/>[DeviceService.java]"]
  node_authcontroller["Auth endpoints"]
  node_reauth["Re-authentication"]
end

subgraph group_monitoring["Behavior and security"]
  node_securitycontroller["Security endpoints"]
  node_behaviorservice["Behavior processing"]
  node_state["Security state machine"]
end

subgraph group_insights["User insights"]
  node_dashboard["Dashboard aggregation"]
  node_alertcontroller["Alert endpoints"]
end

subgraph group_persistence["Persistence and scoring"]
  node_mlapi["ML scoring API<br/>[main.py]"]
  node_ensemble["Anomaly ensemble<br/>[ensemble_model.py]"]
  node_mysql[("MySQL")]
  node_userentity["User records<br/>[User.java]"]
  node_sessionentity["Session records<br/>[UserSession.java]"]
  node_sessionrepo["Session repository"]
  node_alertrepo["Alert repository"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"provides auth"| node_authctx
node_authctx -->|"calls auth API"| node_apiclient
node_authctx -.->|"authenticates via"| node_authcontroller
node_authservice -->|"registers device"| node_deviceservice
node_authservice -->|"creates or reads"| node_userentity
node_authservice -.->|"persists users"| node_mysql
node_collector -->|"submits windows"| node_behaviorclient
node_behaviorclient -->|"uses REST client"| node_apiclient
node_collector -.->|"posts feature windows"| node_securitycontroller
node_securitycontroller -.->|"delegates processing"| node_behaviorservice
node_behaviorservice -.->|"requests risk score"| node_mlapi
node_mlapi -->|"scores anomalies"| node_ensemble
node_mlapi -.->|"returns risk score"| node_securitycontroller
node_securitycontroller -->|"applies risk state"| node_state
node_state -.->|"updates sessions"| node_sessionrepo
node_state -.->|"records alerts"| node_alertrepo
node_sessionrepo -.->|"reads and writes"| node_mysql
node_alertrepo -.->|"reads and writes"| node_mysql
node_state -.->|"requires re-auth"| node_reauth
node_user -->|"re-authenticates"| node_reauth
node_user -.->|"views summary"| node_dashboard
node_dashboard -->|"loads alerts"| node_alertrepo
node_dashboard -->|"loads sessions"| node_sessionrepo
node_user -.->|"views alerts"| node_alertcontroller

click node_app "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/context/AuthContext.jsx"
click node_collector "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/hooks/useBehaviorCollector.js"
click node_behaviorclient "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/services/behaviorService.js"
click node_apiclient "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/services/api.js"
click node_authservice "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/AuthService.java"
click node_deviceservice "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/DeviceService.java"
click node_authcontroller "https://github.com/gnanadhivya/behaviorlock/tree/main/backend/src/main/java/com/behaviorlock/backend/controller"
click node_securitycontroller "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java"
click node_behaviorservice "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/BehaviorService.java"
click node_mlapi "https://github.com/gnanadhivya/behaviorlock/blob/main/ml-service/main.py"
click node_ensemble "https://github.com/gnanadhivya/behaviorlock/blob/main/ml-service/ensemble_model.py"
click node_state "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java"
click node_reauth "https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/pages/ReauthenticatePage.jsx"
click node_dashboard "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/DashboardService.java"
click node_alertcontroller "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/controller/AlertController.java"
click node_userentity "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/entity/User.java"
click node_sessionentity "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/entity/UserSession.java"
click node_sessionrepo "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/repository/UserSessionRepository.java"
click node_alertrepo "https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/repository/SecurityAlertRepository.java"

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,node_authctx,node_collector,node_behaviorclient,node_apiclient,node_user toneBlue
class node_authservice,node_deviceservice,node_authcontroller,node_reauth toneAmber
class node_securitycontroller,node_behaviorservice,node_state toneMint
class node_dashboard,node_alertcontroller toneRose
class node_mlapi,node_ensemble,node_mysql,node_userentity,node_sessionentity,node_sessionrepo,node_alertrepo toneIndigo
```

## Components

### Web client

- [App routes](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Behavior collector](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/hooks/useBehaviorCollector.js): `frontend/src/hooks/useBehaviorCollector.js`
- [Behavior API client](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/services/behaviorService.js): `frontend/src/services/behaviorService.js`
- [REST client](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Identity and devices

- [Authentication](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/AuthService.java): `backend/src/main/java/com/behaviorlock/backend/service/AuthService.java`
- [Device and session service](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/DeviceService.java): `backend/src/main/java/com/behaviorlock/backend/service/DeviceService.java`
- [Auth endpoints](https://github.com/gnanadhivya/behaviorlock/tree/main/backend/src/main/java/com/behaviorlock/backend/controller): `backend/src/main/java/com/behaviorlock/backend/controller`
- [Re-authentication](https://github.com/gnanadhivya/behaviorlock/blob/main/frontend/src/pages/ReauthenticatePage.jsx): `frontend/src/pages/ReauthenticatePage.jsx`

### Behavior and security

- [Security endpoints](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java): `backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java`
- [Behavior processing](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/BehaviorService.java): `backend/src/main/java/com/behaviorlock/backend/service/BehaviorService.java`
- [Security state machine](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java): `backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java`

### User insights

- [Dashboard aggregation](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/service/DashboardService.java): `backend/src/main/java/com/behaviorlock/backend/service/DashboardService.java`
- [Alert endpoints](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/controller/AlertController.java): `backend/src/main/java/com/behaviorlock/backend/controller/AlertController.java`

### Persistence and scoring

- [ML scoring API](https://github.com/gnanadhivya/behaviorlock/blob/main/ml-service/main.py): `ml-service/main.py`
- [Anomaly ensemble](https://github.com/gnanadhivya/behaviorlock/blob/main/ml-service/ensemble_model.py): `ml-service/ensemble_model.py`
- **MySQL**
- [User records](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/entity/User.java): `backend/src/main/java/com/behaviorlock/backend/entity/User.java`
- [Session records](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/entity/UserSession.java): `backend/src/main/java/com/behaviorlock/backend/entity/UserSession.java`
- [Session repository](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/repository/UserSessionRepository.java): `backend/src/main/java/com/behaviorlock/backend/repository/UserSessionRepository.java`
- [Alert repository](https://github.com/gnanadhivya/behaviorlock/blob/main/backend/src/main/java/com/behaviorlock/backend/repository/SecurityAlertRepository.java): `backend/src/main/java/com/behaviorlock/backend/repository/SecurityAlertRepository.java`

### Other components

- **User**

## Connections

- User → App routes: uses (evidence: `frontend/src/App.jsx`)
- App routes → Auth context: provides auth (evidence: `frontend/src/App.jsx`)
- Auth context → REST client: calls auth API (evidence: `frontend/src/context/AuthContext.jsx`)
- Auth context → Auth endpoints: authenticates via
- Authentication → Device and session service: registers device (evidence: `backend/src/main/java/com/behaviorlock/backend/service/AuthService.java`)
- Authentication → User records: creates or reads (evidence: `backend/src/main/java/com/behaviorlock/backend/service/AuthService.java`)
- Authentication → MySQL: persists users
- Behavior collector → Behavior API client: submits windows (evidence: `frontend/src/hooks/useBehaviorCollector.js`)
- Behavior API client → REST client: uses REST client (evidence: `frontend/src/services/behaviorService.js`)
- Behavior collector → Security endpoints: posts feature windows
- Security endpoints → Behavior processing: delegates processing
- Behavior processing → ML scoring API: requests risk score
- ML scoring API → Anomaly ensemble: scores anomalies (evidence: `ml-service/main.py`)
- ML scoring API → Security endpoints: returns risk score
- Security endpoints → Security state machine: applies risk state (evidence: `backend/src/main/java/com/behaviorlock/backend/controller/SecurityController.java`)
- Security state machine → Session repository: updates sessions (evidence: `backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java`)
- Security state machine → Alert repository: records alerts (evidence: `backend/src/main/java/com/behaviorlock/backend/service/SecurityStateMachineService.java`)
- Session repository → MySQL: reads and writes
- Alert repository → MySQL: reads and writes
- Security state machine → Re-authentication: requires re-auth
- User → Re-authentication: re-authenticates
- User → Dashboard aggregation: views summary
- Dashboard aggregation → Alert repository: loads alerts (evidence: `backend/src/main/java/com/behaviorlock/backend/service/DashboardService.java`)
- Dashboard aggregation → Session repository: loads sessions (evidence: `backend/src/main/java/com/behaviorlock/backend/service/DashboardService.java`)
- User → Alert endpoints: views alerts
