generated from wessel/boilerplate
Vincent W
5e1df5367c
Split documentation into three folders: Architecture, Testing and Installation. Rework and expand architecture.md alongside interfaces.md Split all parts to do with testing from Architecture md's into Test md's Add parameter to ExamResultGenerator node documentation
148 lines
5.9 KiB
Markdown
148 lines
5.9 KiB
Markdown
# TI Minor Grade Generator Design Document
|
|
|
|
## Project Overview
|
|
|
|
The TI Minor Grade Generator is a distributed ROS2-based system designed to manage student exam results and calculate final course grades. The system follows microservices architecture principles with clear separation of concerns and robust data management.
|
|
|
|
## System Architecture
|
|
|
|
### High-Level Architecture
|
|
|
|
The system consists of multiple ROS2 nodes that communicate through standardized topics and services to process exam data, calculate grades, and persist results. The architecture ensures scalability, maintainability, and fault tolerance.
|
|
|
|
### Key Design Principles
|
|
|
|
- **Microservices Architecture**: Each component has a single responsibility
|
|
- **Asynchronous Communication**: Uses ROS2 topics and services for loose coupling
|
|
- **Data Persistence**: Centralized database management for reliable storage
|
|
- **Configurable Parameters**: TOML-based configuration for environment flexibility
|
|
- **Comprehensive Testing**: Unit and integration tests ensure reliability
|
|
|
|
## System Components
|
|
|
|
### Core Nodes
|
|
|
|
#### 1. FinalGradeDeterminator Node
|
|
**Namespace**: `assignments::one::final_grade_determinator`
|
|
|
|
**Brief Description**: Collects exam results, triggers grade calculation when thresholds are met, and stores final grades.
|
|
|
|
**Key Features**: Configurable collection thresholds, automatic grade calculation triggering, database persistence
|
|
|
|
*For detailed documentation, see: [FinalGradeDeterminator.md](nodes/FinalGradeDeterminator.md)*
|
|
|
|
#### 2. GradeCalculator Node
|
|
**Namespace**: `assignments::one::grade_calculator`
|
|
|
|
**Brief Description**: Provides grade calculation service with business logic including bonus points and grade validation.
|
|
|
|
**Key Features**: Average calculation, special student rules, grade bounds validation (10-100)
|
|
|
|
*For detailed documentation, see: [GradeCalculator.md](nodes/GradeCalculator.md)*
|
|
|
|
#### 3. ExamResultGenerator Node
|
|
**Namespace**: `assignments::one::exam_result_generator`
|
|
|
|
**Brief Description**: Simulates exam result generation by maintaining a queue of student-course combinations and publishing random grades.
|
|
|
|
**Key Features**: Database-driven queue management, random grade generation, student enrollment handling
|
|
|
|
*For detailed documentation, see: [ExamResultGenerator.md](nodes/ExamResultGenerator.md)*
|
|
|
|
#### 4. RetakeScheduler Node
|
|
**Namespace**: `assignments::one::retake_scheduler`
|
|
|
|
**Brief Description**: Manages retake exam scheduling and coordination for students who need to retake exams.
|
|
|
|
**Key Features**: Retake request processing, schedule management, action server implementation for retake workflows
|
|
|
|
*For detailed documentation, see: [RetakeScheduler.md](nodes/RetakeScheduler.md)*
|
|
|
|
#### 5. RetakeGradeDeterminator Node
|
|
**Namespace**: `assignments::one::retake_grade_determinator`
|
|
|
|
**Brief Description**: Handles grade calculation and processing specifically for retake exams.
|
|
|
|
**Key Features**: Retake-specific grade processing, integration with main grade system, retake result validation
|
|
|
|
*For detailed documentation, see: [RetakeGradeDeterminator.md](nodes/RetakeGradeDeterminator.md)*
|
|
|
|
### Data Management
|
|
|
|
#### DatabaseManager
|
|
**Brief Description**: PostgreSQL database interface handling connections, table management, and data persistence.
|
|
|
|
**Key Features**: Connection management, automatic table creation, student enrollment tracking, exam result storage
|
|
|
|
*For detailed documentation, see: [DatabaseManager.md](../DatabaseManager.md)*
|
|
|
|
#### ConfigManager
|
|
**Brief Description**: TOML-based configuration management system allowing runtime configuration without recompilation.
|
|
|
|
**Key Features**: Automatic config file discovery, type-safe TOML parsing, database connection configuration
|
|
|
|
*For detailed documentation, see: [ConfigManager.md](../ConfigManager.md)*
|
|
|
|
### Communication Interfaces
|
|
|
|
#### ROS2 Message and Service Interfaces
|
|
**Brief Description**: Custom message types and service definitions for inter-node communication.
|
|
|
|
**Key Components**: Exam and Student message types, Grade calculation service, Retake action interface, standardized timestamps
|
|
|
|
*For detailed documentation, see: [interfaces.md](interfaces/interfaces.md)*
|
|
|
|
## System Workflow
|
|
|
|
### 1. Exam Result Processing
|
|
|
|
1. **Input**: Exam results are published to the `exam_results` topic
|
|
2. **Collection**: FinalGradeDeterminator receives and stores exam results by student-course combination
|
|
3. **Monitoring**: System tracks the number of results per student-course pair
|
|
4. **Threshold Check**: When `grade_collection_amount` results are collected, proceed to calculation
|
|
|
|
### 2. Grade Calculation Process
|
|
|
|
1. **Service Request**: FinalGradeDeterminator calls GradeCalculator service
|
|
2. **Calculation**: GradeCalculator computes final grade using business logic
|
|
3. **Validation**: Result is validated and clamped to acceptable range
|
|
4. **Response**: Calculated grade is returned to FinalGradeDeterminator
|
|
|
|
### 3. Result Management
|
|
|
|
1. **Database Storage**: Final grade is persisted in the database
|
|
2. **Publication**: Student information is published to management topic
|
|
3. **Logging**: Process completion is logged for audit purposes
|
|
|
|
### 4. Retake Processing Workflow
|
|
|
|
1. **Retake Request**: RetakeScheduler receives retake requests via action interface
|
|
2. **Schedule Management**: System schedules retake exams and manages timelines
|
|
3. **Retake Execution**: Student completes retake exam, results are processed
|
|
4. **Grade Processing**: RetakeGradeDeterminator calculates retake grades with specialized logic
|
|
5. **Integration**: Retake results are integrated with main grade system and database
|
|
|
|
## Configuration Management
|
|
|
|
### TOML Configuration Structure
|
|
|
|
The system uses TOML files for environment-specific configuration:
|
|
|
|
```toml
|
|
[database]
|
|
host = "localhost"
|
|
port = 5432
|
|
name = "grade_db"
|
|
user = "grade_user"
|
|
password = "secure_password"
|
|
|
|
[grade_calculation]
|
|
collection_amount = 5
|
|
min_grade = 10
|
|
max_grade = 100
|
|
|
|
[logging]
|
|
level = "INFO"
|
|
output_file = "grade_system.log"
|
|
```
|