# lakshyamurali153-source/exam architecture

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

- Interactive diagram: https://gitdiagram.com/lakshyamurali153-source/exam
- Repository: https://github.com/lakshyamurali153-source/exam

## Overview

ExamGuard records and reviews online-exam monitoring events. The primary workflow is a user submitting a session or event through the React interface: Flask checks and normalizes detections, merges repeated detections when requested, and persists closed or direct events in MySQL for filtered review. The backend also exposes an event-ingestion route that invokes the Kafka producer. Kafka consumption and broader integrations are documented as planned; the sampled code does not establish their end-to-end wiring.

Main entry points: [`backend/app.py`](https://github.com/lakshyamurali153-source/exam/blob/main/backend/app.py) (Flask routes), [`backend/normalizer.py`](https://github.com/lakshyamurali153-source/exam/blob/main/backend/normalizer.py) (Detection normalizer), [`backend/event_aggregator.py`](https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_aggregator.py) (Detection aggregator), [`backend/event_repository.py`](https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_repository.py) (Event repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Review Interface"]
  node_ui["Events dashboard<br/>[App.jsx]"]
end

subgraph group_api["Backend API"]
  node_api_service["Flask routes<br/>[app.py]"]
  node_logger["Application logging<br/>[logging_config.py]"]
end

subgraph group_processing["Event Processing"]
  node_normalizer["Detection normalizer<br/>[normalizer.py]"]
  node_validation["Event validation"]
  node_aggregator["Detection aggregator"]
  node_timeutils["Timestamp utilities<br/>[timeutils.py]"]
  node_config["Processing settings<br/>[config.py]"]
end

subgraph group_persistence["Persistence and Streaming"]
  node_event_repo["Event repository"]
  node_session_repo["Session repository"]
  node_database["Database access<br/>[database.py]"]
  node_producer["Kafka producer<br/>[producer.py]"]
  node_consumer["Kafka consumer<br/>[consumer.py]"]
  node_kafka_config["Kafka settings<br/>[kafka_config.py]"]
end

node_user(("Exam operator"))
node_mysql[("MySQL")]
node_kafka["Kafka broker"]

node_user -->|"uses"| node_ui
node_ui -->|"sends requests"| node_api_service
node_api_service -->|"normalizes detections"| node_normalizer
node_api_service -->|"checks session access"| node_validation
node_normalizer -->|"validates input"| node_validation
node_api_service -->|"merges detections"| node_aggregator
node_aggregator -->|"builds events"| node_normalizer
node_api_service -->|"saves and queries"| node_event_repo
node_api_service -->|"manages sessions"| node_session_repo
node_api_service -->|"publishes ingestion"| node_producer
node_api_service -->|"logs requests"| node_logger
node_normalizer -->|"parses timestamps"| node_timeutils
node_event_repo -->|"converts timestamps"| node_timeutils
node_session_repo -->|"converts timestamps"| node_timeutils
node_event_repo -->|"executes queries"| node_database
node_session_repo -->|"executes queries"| node_database
node_database -->|"opens connections"| node_mysql
node_normalizer -->|"reads threshold"| node_config
node_validation -->|"reads tolerance"| node_config
node_aggregator -->|"reads event gap"| node_config
node_producer -->|"loads settings"| node_kafka_config
node_consumer -->|"loads settings"| node_kafka_config
node_producer -.->|"streams events"| node_kafka
node_kafka -.->|"delivers events"| node_consumer

click node_ui "https://github.com/lakshyamurali153-source/exam/blob/main/frontend/src/App.jsx"
click node_api_service "https://github.com/lakshyamurali153-source/exam/blob/main/backend/app.py"
click node_normalizer "https://github.com/lakshyamurali153-source/exam/blob/main/backend/normalizer.py"
click node_validation "https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_validation.py"
click node_aggregator "https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_aggregator.py"
click node_timeutils "https://github.com/lakshyamurali153-source/exam/blob/main/backend/timeutils.py"
click node_config "https://github.com/lakshyamurali153-source/exam/blob/main/backend/config.py"
click node_event_repo "https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_repository.py"
click node_session_repo "https://github.com/lakshyamurali153-source/exam/blob/main/backend/session_repository.py"
click node_database "https://github.com/lakshyamurali153-source/exam/blob/main/backend/database.py"
click node_logger "https://github.com/lakshyamurali153-source/exam/blob/main/backend/logging_config.py"
click node_producer "https://github.com/lakshyamurali153-source/exam/blob/main/backend/producer.py"
click node_consumer "https://github.com/lakshyamurali153-source/exam/blob/main/backend/consumer.py"
click node_kafka_config "https://github.com/lakshyamurali153-source/exam/blob/main/backend/kafka_config.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_ui toneBlue
class node_api_service,node_logger,node_mysql toneAmber
class node_normalizer,node_validation,node_aggregator,node_timeutils,node_config toneMint
class node_event_repo,node_session_repo,node_database,node_producer,node_consumer,node_kafka_config toneRose
class node_user,node_kafka toneIndigo
```

## Components

### Review Interface

- [Events dashboard](https://github.com/lakshyamurali153-source/exam/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Backend API

- [Flask routes](https://github.com/lakshyamurali153-source/exam/blob/main/backend/app.py): `backend/app.py`
- [Application logging](https://github.com/lakshyamurali153-source/exam/blob/main/backend/logging_config.py): `backend/logging_config.py`

### Event Processing

- [Detection normalizer](https://github.com/lakshyamurali153-source/exam/blob/main/backend/normalizer.py): `backend/normalizer.py`
- [Event validation](https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_validation.py): `backend/event_validation.py`
- [Detection aggregator](https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_aggregator.py): `backend/event_aggregator.py`
- [Timestamp utilities](https://github.com/lakshyamurali153-source/exam/blob/main/backend/timeutils.py): `backend/timeutils.py`
- [Processing settings](https://github.com/lakshyamurali153-source/exam/blob/main/backend/config.py): `backend/config.py`

### Persistence and Streaming

- [Event repository](https://github.com/lakshyamurali153-source/exam/blob/main/backend/event_repository.py): `backend/event_repository.py`
- [Session repository](https://github.com/lakshyamurali153-source/exam/blob/main/backend/session_repository.py): `backend/session_repository.py`
- [Database access](https://github.com/lakshyamurali153-source/exam/blob/main/backend/database.py): `backend/database.py`
- [Kafka producer](https://github.com/lakshyamurali153-source/exam/blob/main/backend/producer.py): `backend/producer.py`
- [Kafka consumer](https://github.com/lakshyamurali153-source/exam/blob/main/backend/consumer.py): `backend/consumer.py`
- [Kafka settings](https://github.com/lakshyamurali153-source/exam/blob/main/backend/kafka_config.py): `backend/kafka_config.py`

### Other components

- **Exam operator**
- **MySQL**
- **Kafka broker**

## Connections

- Exam operator → Events dashboard: uses (evidence: `frontend/src/App.jsx`)
- Events dashboard → Flask routes: sends requests (evidence: `frontend/src/App.jsx`)
- Flask routes → Detection normalizer: normalizes detections (evidence: `backend/app.py`)
- Flask routes → Event validation: checks session access (evidence: `backend/app.py`)
- Detection normalizer → Event validation: validates input (evidence: `backend/normalizer.py`)
- Flask routes → Detection aggregator: merges detections (evidence: `backend/app.py`)
- Detection aggregator → Detection normalizer: builds events (evidence: `backend/event_aggregator.py`)
- Flask routes → Event repository: saves and queries (evidence: `backend/app.py`)
- Flask routes → Session repository: manages sessions (evidence: `backend/app.py`)
- Flask routes → Kafka producer: publishes ingestion (evidence: `backend/app.py`)
- Flask routes → Application logging: logs requests (evidence: `backend/app.py`)
- Detection normalizer → Timestamp utilities: parses timestamps (evidence: `backend/normalizer.py`)
- Event repository → Timestamp utilities: converts timestamps (evidence: `backend/event_repository.py`)
- Session repository → Timestamp utilities: converts timestamps (evidence: `backend/session_repository.py`)
- Event repository → Database access: executes queries (evidence: `backend/event_repository.py`)
- Session repository → Database access: executes queries (evidence: `backend/session_repository.py`)
- Database access → MySQL: opens connections (evidence: `backend/database.py`)
- Detection normalizer → Processing settings: reads threshold (evidence: `backend/normalizer.py`)
- Event validation → Processing settings: reads tolerance (evidence: `backend/event_validation.py`)
- Detection aggregator → Processing settings: reads event gap (evidence: `backend/event_aggregator.py`)
- Kafka producer → Kafka settings: loads settings (evidence: `backend/producer.py`)
- Kafka consumer → Kafka settings: loads settings (evidence: `backend/consumer.py`)
- Kafka producer → Kafka broker: streams events
- Kafka broker → Kafka consumer: delivers events