How asanwari/lingoturk works
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)