How gong-io/gecko works
Project type and purpose
• Gecko is primarily a single-page web application for audio annotation, built with Angular.js v1.x and wavesurfer.js.
• It includes auxiliary backend services for file uploads (Node.js S3 proxy), dataset creation (Python DocannoServer script), and optional CLI tools.
• It ships with Docker/Docker-Compose for local deployment but can also be run on a simple static server plus the upload service.
File structure
Top-level:
• Dockerfile, docker-compose.yml – container definitions
• index_server.js – Node.js script to serve the app and wire in APIs
• gecko-upload-server/ – Node.js S3 proxy service (s3.js, s3proxy.js)
• DocannoServer/ – Python dataset creation tools
• tools/presigned.py – Python script to generate S3 presigned URLs
• app/ – Angular application code (controllers, directives, services, templates)
• static/ – prebuilt bundle and assets (CSS, fonts, images, index.html)
• samples/ – example audio and annotation files
• webpack.config.js, package.json – build & dependency management
README for additional insights
• The README confirms the stack (Angular.js + wavesurfer.js), use cases (VAD, diarization, ASR annotation), and deployment instructions.
• No monolithic server – front end is static; back end is minimal (upload proxy, dataset creation).
Main components and interactions (to include
a. Frontend (Browser / Angular.js SPA)
• Loads static assets (HTML/CSS/JS) from a static server (could be Nginx or the Node index_server.js).
• Uses wavesurfer.js to render audio waveforms and handle playback.
• Contains logical layers: controllers, directives (UI widgets), services (dataManager, storeService, eventBus), templates.
b. Backend services
1. Static file server (index_server.js or Nginx) – serves /index.html and static assets.
2. Upload proxy (gecko-upload-server) – Node.js service that accepts audio/annotation uploads and forwards to S3 (uses s3.js, s3proxy.js).
3. Dataset creation (DocannoServer) – Python utility to generate annotation datasets (CreateDataset.py).
4. CLI tools – presigned.py for generating S3 presigned URLs.
c. External services
• AWS S3 (or S3-compatible storage) for storing uploaded audio and annotation files.
• (Optional) Container registry / Docker Hub for images.
d. Data flows
1. User opens the browser → requests index.html + app bundle from static server.
2. Angular app initializes, loads audio sample (local or from S3 via signed URL).
3. User annotates → Angular services post updated annotations to the upload proxy API.
4. Upload proxy streams data to S3.
5. Python tools (DocannoServer, presigned.py) run offline to prepare datasets or URLs.
Architectural patterns and design principles
• MVC/MVVM in Angular.js: controllers/directives/templates + services.
• Modularization: geckoModule is subdivided into directives, services, filters, templates, utils.
• Separation of concerns: UI layer (app/) is fully decoupled from storage & server logic (gecko-upload-server/, DocannoServer/).
• Containerization: each service can run in its own Docker container, orchestrated via docker-compose.