# najidmohamed/annotationapp architecture

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

- Interactive diagram: https://gitdiagram.com/najidmohamed/annotationapp
- Repository: https://github.com/najidmohamed/annotationapp

## Overview

##### Project Type and Purpose
- This is a full-stack, server-rendered web application for managing text annotation tasks.
- Built with Spring Boot (Java), Thymeleaf templates for the UI, Spring Data JPA for persistence, and a relational database (H2/MySQL/PostgreSQL).
- Key use cases: administrators create datasets and assign annotation tasks in bulk; annotators log in, view assigned text pairs, submit annotations.

##### Main Components
A. Client Layer
- Web Browser (UI)
– Renders HTML/CSS/JS served by Thymeleaf templates and static resources.
- REST Client (could be AJAX or external scripts consuming JSON endpoints for task assignment).
B. Web Server Layer (Spring Boot Application)
1. Controllers (Spring MVC)
– Handle incoming HTTP requests (login, admin pages, annotator pages, REST endpoints).
– Package: ma.najid.annotationapp.Controller
2. Service Layer
– Business logic for user accounts, annotators, tasks, datasets, email notifications.
– Interfaces under ma.najid.annotationapp.service; implementations in service.impl.
3. Repository Layer (Spring Data JPA)
– CRUD operations and custom queries for entities (Annotation, Annotator, Dataset, etc.).
– Package: ma.najid.annotationapp.repository
4. Domain Models & DTOs
– Entities (ma.najid.annotationapp.Model) map to database tables.
– DTOs (ma.najid.annotationapp.dto) for request/response payloads, decoupling internal models from API.
5. Configuration & Initialization
– application.properties for datasource and app settings.
– DataInitializer populates initial roles, users, sample data.
– ThymeleafConfig for view resolver customizations.
C. Persistence Layer
- Relational Database
– Tables mirror Entity classes (UserAccount, Tache, Annotation, etc.).
– Schema initialized via migration.sql and JPA.
D. External Services
- Email Service (SMTP) for notifications (package: ma.najid.annotationapp.service.Email).
- File storage (uploads directory for dataset files).

##### Component Interactions and Data Flow
1. User requests a page or REST endpoint from Browser → Spring Controllers.
2. Controller orchestrates:
– Validates input, transforms to DTOs.
– Calls Service layer methods.
3. Service layer applies business rules, uses Repositories to query/update the Database.
4. If needed, Service layer calls EmailService to send notifications.
5. Controller returns:
– Thymeleaf template name + Model attributes → rendered HTML.
– Or JSON response for REST operations.
6. Browser renders response; user interacts further.

##### Architectural Patterns & Principles
- Layered (Presentation → Business → Data).
- MVC for web layer (Thymeleaf views + Controllers).
- Repository pattern via Spring Data JPA.
- Dependency injection throughout.
- DTOs to decouple web API from domain models.
- Configuration classes for modular setup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web Browser"]:::frontend
        Templates["Thymeleaf Templates"]:::frontend
        Static["Static Resources (CSS/JS/Images)"]:::frontend
    end

    %% Web Server Layer
    subgraph "Web Server Layer"
        direction TB
        App["AnnotationAppApplication"]:::backend
        subgraph "Controllers" 
            direction TB
            AdminController["AdminController"]:::backend
            AnnotationController["AnnotationController"]:::backend
            AnnotatorController["AnnotatorController"]:::backend
            DatasetController["DatasetController"]:::backend
            TaskController["TaskController"]:::backend
            LoginController["LoginController"]:::backend
        end
        subgraph "Services"
            direction TB
            AdminSvcInt["AdministratorService"]:::backend
            AnnotatorSvcInt["AnnotatorService"]:::backend
            DatasetSvcInt["DatasetService"]:::backend
            TacheSvcInt["TacheService"]:::backend
            UserAccountSvcInt["UserAccountService"]:::backend
            PossibleClassesSvcInt["PossibleClassesService"]:::backend
            subgraph "Implementations"
                direction TB
                AdminSvcImpl["AdministratorServiceImpl"]:::backend
                AnnotatorSvcImpl["AnnotatorServiceImpl"]:::backend
                DatasetSvcImpl["DatasetServiceImpl"]:::backend
                TacheSvcImpl["TacheServiceImpl"]:::backend
                UserAccountSvcImpl["UserAccountServiceImpl"]:::backend
                PossibleClassesSvcImpl["PossibleClassesServiceImpl"]:::backend
            end
            EmailSvc["EmailService"]:::external
        end
        subgraph "Repositories"
            direction TB
            RepoDir["Repository Layer"]:::data
        end
        subgraph "Domain & DTO"
            direction TB
            ModelDir["Domain Models"]:::data
            DTODir["DTOs"]:::data
        end
        subgraph "Config & Init"
            direction TB
            Props["application.properties"]:::data
            Migrations["migration.sql"]:::data
            DataInit["DataInitializer"]:::backend
            ThymeleafCfg["ThymeleafConfig"]:::backend
        end
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        Database["Relational Database"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP Email Service"]:::external
        FileStore["File Upload Storage"]:::external
    end

    %% Flows
    Browser -->|"HTTP GET/POST"| AdminController
    Browser -->|"HTTP GET/POST"| AnnotationController
    Browser -->|"HTTP GET/POST"| AnnotatorController
    Browser -->|"HTTP GET/POST"| DatasetController
    Browser -->|"HTTP GET/POST"| TaskController
    Browser -->|"HTTP GET/POST"| LoginController
    Templates --> Browser
    Static --> Browser

    AdminController -->|"calls"| AdminSvcInt
    AnnotationController -->|"calls"| AnnotatorSvcInt
    AnnotatorController -->|"calls"| TacheSvcInt
    DatasetController -->|"calls"| DatasetSvcInt
    TaskController -->|"calls"| TacheSvcInt
    LoginController -->|"calls"| UserAccountSvcInt

    AdminSvcInt --> AdminSvcImpl
    AnnotatorSvcInt --> AnnotatorSvcImpl
    DatasetSvcInt --> DatasetSvcImpl
    TacheSvcInt --> TacheSvcImpl
    UserAccountSvcInt --> UserAccountSvcImpl
    PossibleClassesSvcInt --> PossibleClassesSvcImpl

    AdminSvcImpl --> RepoDir
    AnnotatorSvcImpl --> RepoDir
    DatasetSvcImpl --> RepoDir
    TacheSvcImpl --> RepoDir
    UserAccountSvcImpl --> RepoDir
    PossibleClassesSvcImpl --> RepoDir

    RepoDir --> Database
    DataInit --> RepoDir
    DataInit --> Database

    DatasetSvcImpl -->|reads/writes| FileStore
    AdminSvcImpl -->|send notification| EmailSvc
    EmailSvc --> SMTP

    %% Click Events
    click App "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/AnnotationAppApplication.java"
    click AdminController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click AnnotationController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click AnnotatorController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click DatasetController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click TaskController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click LoginController "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Controller"
    click AdminSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/AdministratorService.java"
    click AnnotatorSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/AnnotatorService.java"
    click DatasetSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/DatasetService.java"
    click TacheSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/TacheService.java"
    click UserAccountSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/UserAccountService.java"
    click PossibleClassesSvcInt "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/PossibleClassesService.java"
    click AdminSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/AdministratorServiceImpl.java"
    click AnnotatorSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/AnnotatorServiceImpl.java"
    click DatasetSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/DatasetServiceImpl.java"
    click TacheSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/TacheServiceImpl.java"
    click UserAccountSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/UserAccountServiceImpl.java"
    click PossibleClassesSvcImpl "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/impl/PossibleClassesServiceImpl.java"
    click EmailSvc "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/service/Email/EmailService.java"
    click RepoDir "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/repository"
    click ModelDir "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/Model"
    click DTODir "https://github.com/najidmohamed/annotationapp/tree/main/src/main/java/ma/najid/annotationapp/dto"
    click Props "https://github.com/najidmohamed/annotationapp/blob/main/src/main/resources/application.properties"
    click Migrations "https://github.com/najidmohamed/annotationapp/blob/main/src/main/resources/migration.sql"
    click DataInit "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/config/DataInitializer.java"
    click ThymeleafCfg "https://github.com/najidmohamed/annotationapp/blob/main/src/main/java/ma/najid/annotationapp/config/ThymeleafConfig.java"
    click Templates "https://github.com/najidmohamed/annotationapp/tree/main/src/main/resources/templates"
    click Static "https://github.com/najidmohamed/annotationapp/tree/main/src/main/resources/static"
    click FileStore "https://github.com/najidmohamed/annotationapp/tree/main/uploads"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#1E70BF,stroke-width:1px
    classDef backend fill:#DFF0D8,stroke:#3C763D,stroke-width:1px
    classDef data fill:#FDF5E6,stroke:#8A6D3B,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#AAA,stroke-dasharray: 5 5
```
