# gong-io/gecko architecture

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

- Interactive diagram: https://gitdiagram.com/gong-io/gecko
- Repository: https://github.com/gong-io/gecko

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Browser and Frontend
    subgraph "Browser (User)"
        Browser["Browser"]:::external
        subgraph "Angular.js SPA"
            SPA["Frontend (Angular.js + wavesurfer.js)"]:::frontend
        end
    end

    %% Static File Server
    subgraph "Static File Server"
        IndexServer["index_server.js"]:::backend
        StaticAssets["static/"]:::backend
    end

    %% Upload Proxy Service
    subgraph "Upload Proxy API"
        UploadProxy["Upload Proxy API"]:::backend
        S3JS["s3.js"]:::backend
        S3Proxy["s3proxy.js"]:::backend
    end

    %% Dataset Creation Service
    subgraph "Dataset Creation (Python)"
        CreateDataset["CreateDataset.py"]:::backend
    end

    %% CLI tool
    Presigned["presigned.py"]:::cli

    %% External Storage
    S3["AWS S3"]:::storage

    %% Docker Compose grouping
    subgraph "Docker Compose" 
        direction TB
        IndexServer
        StaticAssets
        UploadProxy
        S3JS
        S3Proxy
        CreateDataset
    end

    %% Data Flows
    Browser -->|"GET HTML/CSS/JS"| IndexServer
    IndexServer --> StaticAssets
    Browser --> SPA
    SPA -->|"POST annotations"| UploadProxy
    SPA -->|"GET presigned URL"| Presigned
    UploadProxy -->|"PUT objects"| S3
    CreateDataset -->|"reads/writes datasets"| S3

    %% Click Events
    click SPA "https://github.com/gong-io/gecko/tree/master/app/"
    click IndexServer "https://github.com/gong-io/gecko/blob/master/index_server.js"
    click StaticAssets "https://github.com/gong-io/gecko/tree/master/static/"
    click S3JS "https://github.com/gong-io/gecko/blob/master/gecko-upload-server/s3.js"
    click S3Proxy "https://github.com/gong-io/gecko/blob/master/gecko-upload-server/s3proxy.js"
    click CreateDataset "https://github.com/gong-io/gecko/blob/master/DocannoServer/CreateDataset.py"
    click Presigned "https://github.com/gong-io/gecko/blob/master/tools/presigned.py"
    click IndexServer "https://github.com/gong-io/gecko/blob/master/docker-compose.yml"
    click IndexServer "https://github.com/gong-io/gecko/tree/master/Dockerfile"
    click IndexServer "https://github.com/gong-io/gecko/blob/master/package.json"
    click IndexServer "https://github.com/gong-io/gecko/blob/master/webpack.config.js"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px
    classDef storage fill:#ffdead,stroke:#000,stroke-width:1px
    classDef external fill:#f5f5f5,stroke:#000,stroke-width:1px
    classDef cli fill:#d3d3d3,stroke:#000,stroke-width:1px,dasharray:5 5
```
