# aalto-grades/aalto-grades architecture

> Architecture diagram of the GitHub repository aalto-grades/aalto-grades, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aalto-grades/aalto-grades
- Repository: https://github.com/aalto-grades/aalto-grades

## Overview

##### Main System Components

a) Client Layer (Frontend)
- React-based web application
- Components for course management, grading, and user administration
- i18n support for multiple languages
- Material UI components (implied by the structure)

b) Server Layer (Backend)
- Node.js REST API server
- Authentication/Authorization system
- Database controllers and utilities
- Integration with external systems (A+ LMS)

c) Database Layer
- PostgreSQL database (implied by migrations and Sequelize usage)
- Models for courses, grades, users, and other entities

d) External Systems
- A+ Learning Management System integration
- SISU (grade export system)

##### Key Architectural Elements to Highlight

a) Frontend Architecture:
- Component-based structure with clear separation of concerns
- Context providers for auth, grades table, and graph management
- API hooks layer for data fetching
- Shared components and utilities

b) Backend Architecture:
- MVC-like pattern with controllers, routes, and models
- Middleware layer for auth, rate limiting, and error handling
- Swagger/OpenAPI documentation
- Database migrations and seeding system

##### Specific Implementation Details

Important features:

a) Authentication Flow:
- Multiple auth methods (local, external)
- MFA support
- Role-based access control

b) Grade Management:
- Course parts and tasks hierarchy
- Grade calculation system
- Import/export capabilities

- Reverse Proxy                                       |

- ↓

- Client Layer      |    |   Server Layer   |    |     External Systems    |
- (React + Material UI)  | ←→ | (Node.js + REST) | ←→ | (A+ LMS, SISU)         |

- ↕

- Database Layer   |
- (PostgreSQL)     |

##### Component Relationships

Key interactions:

- Client-Server communication via REST API
- Authentication flow between components
- Database operations and relationships
- External system integrations
- Grade calculation and processing flow

##### Additional Details

Elements:

- API endpoints grouping
- Security layers
- Data flow directions
- Caching mechanisms (if any)
- Error handling paths
- User role access paths

##### Technical Stack Callouts

Technologies:

- Frontend: React, TypeScript, Material UI, i18next
- Backend: Node.js, Express, Sequelize
- Testing: Jest, Playwright
- Infrastructure: Docker, Docker Compose
- Documentation: Swagger/OpenAPI

Remember to include notes about scalability considerations and potential future integration points, as this appears to be an actively developed system.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef frontend fill:#3498db,color:white
    classDef backend fill:#2ecc71,color:white
    classDef database fill:#f1c40f,color:white
    classDef external fill:#95a5a6,color:white
    classDef auth fill:#e74c3c,color:white
    
    %% Main Layers
    subgraph Client["Client Layer"]
        FE["Frontend App"]:::frontend
        click FE "https://github.com/aalto-grades/aalto-grades/blob/dev/client/src/App.tsx"
        
        subgraph Components["React Components"]
            UI["Material UI Components"]:::frontend
            I18N["i18n Support"]:::frontend
            click I18N "https://github.com/aalto-grades/aalto-grades/tree/dev/client/public/locales/"
            
            APIHooks["API Hooks"]:::frontend
            click APIHooks "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/hooks/api/"
            
            SharedComps["Shared Components"]:::frontend
            click SharedComps "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/components/shared/"
        end
        
        subgraph Features["Feature Components"]
            CourseManagement["Course Management"]:::frontend
            click CourseManagement "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/components/course/"
            
            GradeManagement["Grade Management"]:::frontend
            click GradeManagement "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/components/course/course-results-view/"
            
            UserManagement["User Management"]:::frontend
            click UserManagement "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/components/front-page/users/"
            
            GraphSystem["Graph System"]:::frontend
            click GraphSystem "https://github.com/aalto-grades/aalto-grades/tree/dev/client/src/components/shared/graph/"
        end
    end
    
    subgraph Server["Server Layer"]
        API["REST API Server"]:::backend
        
        subgraph Controllers["Controllers"]
            AuthController["Auth Controller"]:::backend
            click AuthController "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/controllers/auth.ts"
            
            CourseController["Course Controller"]:::backend
            click CourseController "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/controllers/course.ts"
            
            GradeController["Grade Controller"]:::backend
            click GradeController "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/controllers/taskGrade.ts"
            
            UserController["User Controller"]:::backend
            click UserController "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/controllers/user.ts"
            
            APlusController["A+ Controller"]:::backend
            click APlusController "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/controllers/aplus.ts"
        end
        
        subgraph Middleware["Middleware"]
            AuthMiddleware["Auth Middleware"]:::auth
            click AuthMiddleware "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/middleware/authentication.ts"
            RateLimit["Rate Limiting"]:::backend
            ErrorHandler["Error Handling"]:::backend
        end
        
        Routes["API Routes"]:::backend
        click Routes "https://github.com/aalto-grades/aalto-grades/tree/dev/server/src/routes/"
    end
    
    subgraph DB["Database Layer"]
        PostgreSQL["PostgreSQL Database"]:::database
        
        subgraph Models["Database Models"]
            CourseModel["Course Model"]:::database
            click CourseModel "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/database/models/course.ts"
            
            GradeModel["Grade Model"]:::database
            click GradeModel "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/database/models/taskGrade.ts"
            
            UserModel["User Model"]:::database
            click UserModel "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/database/models/user.ts"
        end
        
        DBConfig["Database Config"]:::database
        click DBConfig "https://github.com/aalto-grades/aalto-grades/blob/dev/server/src/configs/database.ts"
        
        Migrations["Migrations"]:::database
        click Migrations "https://github.com/aalto-grades/aalto-grades/tree/dev/server/src/database/migrations/"
    end
    
    subgraph External["External Systems"]
        APlusLMS["A+ LMS"]:::external
        SISU["SISU"]:::external
    end
    
    %% Relationships
    FE --> API
    API --> PostgreSQL
    API --> APlusLMS
    API --> SISU
    AuthMiddleware --> API
    
    %% Component connections
    Components --> Features
    Features --> APIHooks
    Controllers --> Routes
    Routes --> Models
    
    %% Legend
    subgraph Legend
        Frontend["Frontend"]:::frontend
        Backend["Backend"]:::backend
        DatabaseLegend["Database"]:::database
        ExternalLegend["External Systems"]:::external
        AuthLegend["Auth Components"]:::auth
    end
```
