# h1s4g10rc4/cloud_cell_annotation_tools architecture

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

- Interactive diagram: https://gitdiagram.com/h1s4g10rc4/cloud_cell_annotation_tools
- Repository: https://github.com/h1s4g10rc4/cloud_cell_annotation_tools

## Overview

##### Project Type and Purpose
- Project type: Full-stack web application for collaborative cell-centroid annotation.
- Purpose: Provide a bias-reduced, cooperative annotation workbench with admin dashboards, automated assignment, quality control, and export services.

##### File Structure
- src/ (MVC layers)
– config/ (database, session)
– controllers/ (Express route handlers for admin, auth, detect, work, quality)
– models/ (User, Project, Image, Annotation ORM classes)
– services/ (business logic, e.g. randomAssignmentService, qualityControlService)
– middleware/ (authentication)
– routes/ (Express routing modules)
- views/ & public/ (Handlebars templates, CSS/JS assets)
- scripts/ (stand-alone Node services: scan-images, file-watcher, export, scheduler)
- Dockerfile & docker-compose.yml (container definitions)
- nginx.conf (reverse proxy configuration)
- .env/.env.example (configuration)

##### Review README Insights
- Three primary tiers: Frontend (Handlebars + Vanilla JS), Backend (Node.js + Express + PostgreSQL), Infrastructure (Docker + Nginx).
- Core algorithm: “协調型動的ランダム選択サービス” in services/randomAssignmentService.js.
- Auxiliary processes: file-watcher, scheduled export, migration scripts.

##### Main Components
a. Clients
– Annotator UI (canvas-based annotation in browser)
– Admin dashboard (management pages under /admin)
b. Reverse Proxy
– Nginx container handling SSL, routing to Node app
c. Application Server
– Node.js + Express monolith
– API layer (/api endpoints)
– MVC layers (controllers → services → models)
d. Database
– PostgreSQL container (data persistence: users, projects, images, annotations, grid_status, user_targets)
e. Shared Storage
– data/ directory (image files and detection results)
– exports/ (annotation exports)
– logs/ (application logs)
f. Background Workers (as separate containers or processes)
– file-watcher-service.js (auto-import new images)
– scheduled-export-service.js (cron-driven exports)
– any one-off scripts (scan-images, migrate-quality-images)

##### Relationships and Data Flows
- Browser ↔ Nginx: HTTP(S) requests for static assets and dynamic pages
- Nginx → Node.js: forwards requests to Express (HTTP proxy)
- Node.js → PostgreSQL: queries and updates (via config/database.js)
- Node.js → File system: reads/writes image files, detection outputs, exports
- Node.js (controllers) → services → models: layered call chain
- Background workers → PostgreSQL & file system: scanning, scheduling, exporting
- Admin UI → Node.js (adminController) → database/file operations
- Annotator UI → Node.js (detectController & workController) → randomAssignmentService → database

##### Architectural Patterns & Design Principles
- Layered MVC (separation of concerns)
- Service-oriented within monolith (distinct service classes for assignment, quality control)
- RESTful API for programmatic access (GET /api/work/next, POST /api/work/complete, etc.)
- Containerization (Docker Compose orchestrates app, DB, and reverse proxy)
- Automated background tasks (scripts as lightweight micro-processes)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        AnnotatorUI["Annotator UI"]:::frontend
        AdminUI["Admin Dashboard"]:::frontend
    end

    %% Infrastructure boundary
    subgraph "Docker Compose Cluster"
        direction TB

        %% Reverse Proxy
        Nginx["Nginx Proxy"]:::proxy

        %% Application Container
        subgraph "App Container"
            direction TB
            ExpressApp["Express App"]:::backend

            subgraph "Configuration"
                direction TB
                DBConfig["database.js"]:::backend
                SessionConfig["session.js"]:::backend
            end

            subgraph "Controllers"
                direction TB
                AdminController["adminController.js"]:::backend
                AuthController["authController.js"]:::backend
                DetectController["detectController.js"]:::backend
                ImageUploadController["imageUploadController.js"]:::backend
                MainController["mainController.js"]:::backend
                QualityController["qualityController.js"]:::backend
                WorkController["workController.js"]:::backend
            end

            subgraph "Services"
                direction TB
                RandomAssignmentService["randomAssignmentService.js"]:::backend
                QualityControlService["qualityControlService.js"]:::backend
                QualityProgressService["qualityProgressService.js"]:::backend
            end

            subgraph "Models"
                direction TB
                UserModel["User.js"]:::backend
                ProjectModel["Project.js"]:::backend
                ImageModel["Image.js"]:::backend
                AnnotationModel["Annotation.js"]:::backend
            end

            subgraph "Middleware"
                direction TB
                AuthMiddleware["auth.js"]:::backend
            end

            subgraph "Routes"
                direction TB
                AdminRoutes["admin.js"]:::backend
                ApiRoutes["api.js"]:::backend
                AuthRoutes["auth.js"]:::backend
                DetectRoutes["detect.js"]:::backend
                MainRoutes["main.js"]:::backend
                QualityRoutes["quality.js"]:::backend
            end

            AppEntry["app.js"]:::backend
        end

        %% Database Container
        PostgreSQL["PostgreSQL"]:::db

    end

    %% Local File System
    subgraph "Local FS"
        direction TB
        DataDir["data/"]:::storage
        ExportsDir["exports/"]:::storage
        LogsDir["logs/"]:::storage
    end

    %% Background Workers
    subgraph "Background Workers"
        direction TB
        FileWatcher["file-watcher-service.js"]:::worker
        ScheduledExport["scheduled-export-service.js"]:::worker
        ScanImages["scan-images.js"]:::worker
        ScanQuality["scan-quality-images.js"]:::worker
        ExportAnnotations["export-annotations.js"]:::worker
        MigrateQuality["migrate-quality-images.js"]:::worker
    end

    %% Static Assets and Views
    subgraph "Frontend Assets"
        direction TB
        ViewsAdmin["views/admin/*.hbs"]:::frontend
        ViewsAuth["views/auth/*.hbs"]:::frontend
        ViewsDetect["views/detect.hbs"]:::frontend
        ViewsHome["views/home.hbs"]:::frontend
        Layouts["views/layouts/main.hbs"]:::frontend
        CSS["public/css/*.css"]:::frontend
        JS["public/js/*.js"]:::frontend
        Images["public/images/"]:::frontend
    end

    %% Infrastructure files
    Dockerfile["Dockerfile"]:::backend
    Compose["docker-compose.yml"]:::backend
    NginxConf["nginx.conf"]:::backend
    EnvExample[".env.example"]:::backend

    %% Connections
    AnnotatorUI -->|HTTPS| Nginx
    AdminUI -->|HTTPS| Nginx
    Nginx -->|Proxy| ExpressApp
    ExpressApp -->|SQL| PostgreSQL
    ExpressApp -->|Read/Write| DataDir
    ExpressApp -->|Read/Write| ExportsDir
    ExpressApp -->|Write Logs| LogsDir

    ExpressApp --> DBConfig
    ExpressApp --> SessionConfig
    ExpressApp --> AdminController
    ExpressApp --> AuthController
    ExpressApp --> DetectController
    ExpressApp --> ImageUploadController
    ExpressApp --> MainController
    ExpressApp --> QualityController
    ExpressApp --> WorkController
    ExpressApp --> RandomAssignmentService
    ExpressApp --> QualityControlService
    ExpressApp --> QualityProgressService
    ExpressApp --> UserModel
    ExpressApp --> ProjectModel
    ExpressApp --> ImageModel
    ExpressApp --> AnnotationModel
    ExpressApp --> AuthMiddleware
    ExpressApp --> AdminRoutes
    ExpressApp --> ApiRoutes
    ExpressApp --> AuthRoutes
    ExpressApp --> DetectRoutes
    ExpressApp --> MainRoutes
    ExpressApp --> QualityRoutes
    ExpressApp --> AppEntry

    FileWatcher -->|FS & DB| PostgreSQL
    FileWatcher -->|FS| DataDir
    ScheduledExport -->|FS & DB| ExportsDir
    ScheduledExport -->|DB| PostgreSQL
    ScanImages -->|FS| DataDir
    ScanQuality -->|FS| DataDir
    ExportAnnotations -->|FS & DB| ExportsDir
    ExportAnnotations -->|DB| PostgreSQL
    MigrateQuality -->|DB & FS| PostgreSQL
    MigrateQuality -->|FS| DataDir

    %% Click Events
    click DBConfig "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/config/database.js"
    click SessionConfig "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/config/session.js"
    click AdminController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/adminController.js"
    click AuthController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/authController.js"
    click DetectController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/detectController.js"
    click ImageUploadController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/imageUploadController.js"
    click MainController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/mainController.js"
    click QualityController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/qualityController.js"
    click WorkController "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/controllers/workController.js"
    click RandomAssignmentService "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/services/randomAssignmentService.js"
    click QualityControlService "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/services/qualityControlService.js"
    click QualityProgressService "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/services/qualityProgressService.js"
    click AuthMiddleware "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/middleware/auth.js"
    click AdminRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/admin.js"
    click ApiRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/api.js"
    click AuthRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/auth.js"
    click DetectRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/detect.js"
    click MainRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/main.js"
    click QualityRoutes "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/routes/quality.js"
    click UserModel "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/models/User.js"
    click ProjectModel "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/models/Project.js"
    click ImageModel "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/models/Image.js"
    click AnnotationModel "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/models/Annotation.js"
    click FileWatcher "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/file-watcher-service.js"
    click ScheduledExport "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/scheduled-export-service.js"
    click ScanImages "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/scan-images.js"
    click ScanQuality "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/scan-quality-images.js"
    click ExportAnnotations "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/export-annotations.js"
    click MigrateQuality "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/scripts/migrate-quality-images.js"
    click AppEntry "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/src/app.js"
    click Dockerfile "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/tree/main/Dockerfile"
    click Compose "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/docker-compose.yml"
    click NginxConf "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/nginx.conf"
    click EnvExample "https://github.com/h1s4g10rc4/cloud_cell_annotation_tools/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef worker fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef proxy fill:#f0f0f0,stroke:#666666,color:#333333
```
