# asanwari/lingoturk architecture

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

- Interactive diagram: https://gitdiagram.com/asanwari/lingoturk
- Repository: https://github.com/asanwari/lingoturk

## Overview

##### Project Type & Purpose
- LingoTurk is a full-stack, monolithic web application for hosting and managing custom psycholinguistic experiments.
- Backend: Java (Play Framework + Guice/Deadbolt for DI & auth)
- Frontend: Scala HTML templates, static assets (JS, CSS), jQuery/Prototype, Bootstrap

##### Main Architectural Components
A. Entry Point & Routing
- conf/routes → Play router maps HTTP methods & URLs to Controller actions.
- Module.java + Guice bindings → dependency injection for controllers & services.
B. Controllers (app/controllers)
- ExperimentController, PublishController, ExtractionController, etc.
- Each controller handles a slice of functionality (creation, rendering, publishing, extraction).
- AssetController serves static files; LoginController & SettingsController handle auth & config.
C. Services (app/services)
- DatabaseService (JDBC via commons-dbcp, evolutions)
- MechanicalTurkService & Prolific connector
- ExperimentWatchService (schedules asynchronous tasks)
- LingoturkConfig (reads lingoturk.properties, mturk.properties)
D. Models (app/models)
- Domain objects: Experiment definitions, ParticipantStatistics, Results, User, Worker.
- QuestionFactory & per-experiment subpackages → factory pattern for new experiment types.
- AbstractFactory → group management (FullGroup, DisjointGroup, etc.).
E. Views & Templates
- app/views/*.scala.html → server-side templates injected with model data.
- public/templates/*.html → client-side fragments for AngularJS/directives.
F. Static Assets (public/)
- JavaScript under public/javascripts (ExperimentRendering, ExperimentCreation, etc.)
- CSS under public/stylesheets
- Images & fonts
G. Persistence & Configuration
- conf/application.conf & conf/evolutions/*.sql → DB connection & schema management
- lib/*.jar → third-party dependencies (MTurk API, Apache commons, JDOM, Velocity)
- SBT build scripts (build.sbt, project/plugins.sbt)

##### Component Interactions & Data Flow
1. Browser → HTTP request → Play Router (conf/routes)
2. Router dispatch → Controller (e.g., ExperimentController.render(id))
3. Controller invokes Service (e.g., DatabaseService, MechanicalTurkService)
4. Service → reads/writes Database (via JDBC pool) or calls external APIs (AWS MTurk REST/WSDL, Prolific)
5. Service returns domain model → Controller selects view → renders Scala template
6. Template renders HTML + injects JS/CSS → Response → Browser
7. Asynchronous tasks (ExperimentWatchService) periodically poll MTurk for HITs, update DB

##### Architectural Patterns & Principles
- MVC: separation of concerns among Controllers, Models, Views
- Dependency Injection: Guice modules (Module.java) for loose coupling
- Factory Pattern: QuestionFactory & GroupFactory for extensibility
- Layered Architecture: HTTP layer → Controller → Service → Data layer → Persistence/External API
- Modular Experiment Plugins: each experiment type lives in its own package with properties, SQL, templates, JS

##### Technologies & Frameworks
- Play Framework (Java API, Scala templates)
- SBT for build & dependency management
- Guice & Deadbolt for security & DI
- PostgreSQL/MySQL via Play evolutions & commons-dbcp
- AWS MTurk API (java-aws-mturk.jar, axis/wsdl)
- Prolific integration via REST and config files
- Frontend: jQuery, Prototype.js, Bootstrap CSS, custom JS modules

##### Final Checklist
- Callouts for key folders & files mapping to each component
- Zoom-ins for critical flows (experiment creation, publishing, result extraction)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph "Legend"
        UI["Web Client (Browser)"]:::ui
        DB["Database"]:::db
        EXT["External Services"]:::external
        AS["Static Assets"]:::static
        CTRL["Controllers"]:::controllers
        SVC["Services"]:::services
        MDL["Models"]:::models
        VE["View Engine"]:::views
    end

    %% Client
    UI["Web Client (Browser)"]:::ui

    %% Static Assets
    AS["Static Asset Server\n(public directory)"]:::static
    click AS "https://github.com/asanwari/lingoturk/tree/master/lingoturk/public/"

    %% Play Server
    subgraph "Play Server"
        Router["Play Router\n(conf/routes)"]:::controllers
        click Router "https://github.com/asanwari/lingoturk/tree/master/lingoturk/conf/routes"
        Module["Guice Module\n(app/Module.java)"]:::services
        click Module "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/Module.java"

        subgraph "Controllers"
            ApplicationController["ApplicationController"]:::controllers
            click ApplicationController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/ApplicationController.java"
            AssetController["AssetController"]:::controllers
            click AssetController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/AssetController.java"
            ExperimentController["ExperimentController"]:::controllers
            click ExperimentController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/ExperimentController.java"
            ExperimentTypeController["ExperimentTypeController"]:::controllers
            click ExperimentTypeController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/ExperimentTypeController.java"
            ExtractionController["ExtractionController"]:::controllers
            click ExtractionController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/ExtractionController.java"
            LoginController["LoginController"]:::controllers
            click LoginController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/LoginController.java"
            PublishController["PublishController"]:::controllers
            click PublishController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/PublishController.java"
            RenderController["RenderController"]:::controllers
            click RenderController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/RenderController.java"
            ResultController["ResultController"]:::controllers
            click ResultController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/ResultController.java"
            SettingsController["SettingsController"]:::controllers
            click SettingsController "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/controllers/SettingsController.java"
        end

        subgraph "Services"
            AppInit["AppInitializationService"]:::services
            click AppInit "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/AppInitalizationService.java"
            DBModule["DatabaseModuleService"]:::services
            click DBModule "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/DatabaseModuleService.java"
            DatabaseServiceInterface["DatabaseService (Interface)"]:::services
            click DatabaseServiceInterface "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/DatabaseService.java"
            DatabaseServiceImpl["DatabaseServiceImplementation"]:::services
            click DatabaseServiceImpl "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/DatabaseServiceImplementation.java"
            WatcherInterface["ExperimentWatchService (Interface)"]:::services
            click WatcherInterface "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/ExperimentWatchService.java"
            WatcherImpl["ExperimentWatchServiceImplementation"]:::services
            click WatcherImpl "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/ExperimentWatchServiceImplementation.java"
            ConfigInterface["LingoturkConfig (Interface)"]:::services
            click ConfigInterface "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/LingoturkConfig.java"
            ConfigImpl["LingoturkConfigImplementation"]:::services
            click ConfigImpl "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/LingoturkConfigImplementation.java"
            MTurkService["MechanicalTurkService"]:::services
            click MTurkService "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/services/MechanicalTurkService.java"
        end

        subgraph "Models"
            LingoExp["LingoExpModel"]:::models
            click LingoExp "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/LingoExpModel.java"
            ParticipantStats["ParticipantStatistics"]:::models
            click ParticipantStats "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/ParticipantStatistics.java"
            ParticipantFeedback["ParticipantFeedback"]:::models
            click ParticipantFeedback "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/ParticipantFeedback.java"
            ResultsModel["Results"]:::models
            click ResultsModel "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Results/Results.java"
            User["User"]:::models
            click User "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/User.java"
            Worker["Worker"]:::models
            click Worker "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Worker.java"
            AbstractFactory["AbstractFactory"]:::models
            click AbstractFactory "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/AbstractFactory.java"
            GroupFactory["GroupFactory"]:::models
            click GroupFactory "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Groups/GroupFactory.java"
            AbstractGroup["AbstractGroup"]:::models
            click AbstractGroup "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Groups/AbstractGroup.java"
            DisjointGroup["DisjointGroup"]:::models
            click DisjointGroup "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Groups/DisjointGroup.java"
            FullGroup["FullGroup"]:::models
            click FullGroup "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Groups/FullGroup.java"
            PoolGroup["PoolGroup"]:::models
            click PoolGroup "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Groups/PoolGroup.java"
            QuestionFactory["QuestionFactory"]:::models
            click QuestionFactory "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Questions/QuestionFactory.java"
            QuestionBase["Question"]:::models
            click QuestionBase "https://github.com/asanwari/lingoturk/blob/master/lingoturk/app/models/Questions/Question.java"
        end

        VE["View Engine\n(Scala Templates)"]:::views
        click VE "https://github.com/asanwari/lingoturk/tree/master/lingoturk/app/views/"
    end

    %% Database
    DB["Database\n(PostgreSQL/MySQL)"]:::db
    click DB "https://github.com/asanwari/lingoturk/blob/master/lingoturk/conf/evolutions/default/2.sql"

    %% External Services
    subgraph "External Services"
        MTurk["AWS MTurk"]:::external
        Prolific["Prolific"]:::external
    end

    %% Config & Build
    subgraph "Configuration & Build"
        AppConf["application.conf"]:::static
        click AppConf "https://github.com/asanwari/lingoturk/blob/master/lingoturk/conf/application.conf"
        Props1["lingoturk.properties"]:::static
        click Props1 "https://github.com/asanwari/lingoturk/blob/master/lingoturk/conf/lingoturk.properties"
        Props2["mturk.properties"]:::static
        click Props2 "https://github.com/asanwari/lingoturk/blob/master/lingoturk/conf/mturk.properties"
        Evolutions["evolutions SQL"]:::static
        click Evolutions "https://github.com/asanwari/lingoturk/tree/master/lingoturk/conf/evolutions/"
        BuildSbt["build.sbt"]:::static
        click BuildSbt "https://github.com/asanwari/lingoturk/blob/master/lingoturk/build.sbt"
    end

    %% Flows
    UI -->|"HTTP(S)"| Router
    Router --> Controllers
    Controllers --> Services
    Services -->|"JDBC"| DB
    Services -->|"REST/WSDL"| MTurk
    Services -->|"REST"| Prolific
    Controllers -->|"renders"| VE
    VE --> UI
    UI -->|"fetch JS/CSS"| AS
    Controllers -->|"serves static"| AS

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef controllers fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef services fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef models fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef views fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef db fill:#ffccbc,stroke:#bf360c,stroke-width:1px
    classDef external fill:#cfd8dc,stroke:#607d8b,stroke-width:1px
    classDef static fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
```
