How h1s4g10rc4/cloud_cell_annotation_tools works
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)