ros2-assignments/doc/architecture/architecture.md

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

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

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

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

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

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

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

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

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:

[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"