How maskopav/task_protocoller_web_app works
1. Repo shape: a full-stack monorepo
- The repository is split into a Node.js backend and a React/Vite frontend.
- The backend exposes a JSON API and manages persistence.
- The frontend is a browser-based application with two major modes: participant testing and administrator/researcher management.
2. Primary runtime and persistence
- The backend runs on Node.js and talks to a MariaDB/MySQL database through a dedicated connection layer.
- Database schema is created and seeded from SQL files in backend/scripts/schema and backend/scripts/seed.
- Initialization is explicit: the repo includes setup tooling to create tables, views, seed data, and other helper SQL operations.
3. Backend is organized by domain controllers and routes
- backend/src/routes maps HTTP endpoints for core entities: auth, users, projects, protocols, participants, participantProtocols, sessions, recordings, taskResults, userProjects, and mappings.
- Each route is backed by a corresponding controller in backend/src/controllers.
- This is a classic layered API boundary: routes handle transport, controllers implement business actions, and the database layer handles queries.
4. Core data model and domain boundaries
- The repository centers on a study workflow with these main entities:
- Users and user-project assignments
- Projects
- Protocols and protocol-to-participant assignments
- Participants
- Sessions
- Recordings
- Task results
- Mappings for configurable task/content relationships
- This suggests the system is designed around study configuration, participant enrollment, execution, and result capture rather than generic CRUD alone.
5. Participant flow through the system
- Participants authenticate through the auth layer, then receive a project/protocol assignment.
- The frontend guides them through a protocol-defined sequence of tasks.
- During the session, the browser captures audio/video and records task outcomes.
- The resulting artifacts and metadata are sent back to backend endpoints for persistence in sessions, recordings, and taskResults.
6. Administrator flow and management console
- The admin side of the frontend contains dashboards and management pages for:
- project management
- protocol editing
- participant management
- admin/user assignment
- project statistics and fieldwork tracking
- These screens map closely to backend entities and are likely the primary way researchers configure studies without code changes.
7. Protocol-driven and configuration-driven task architecture
- The frontend includes a substantial protocol/task subsystem:
- ProtocolEditor, ProtocolDashboard, Protocols, TaskLayout
- task-specific components for voice/speech, SDMT, and vision/D-15
- frontend/src/config/tasksBase.ts, frontend/src/tasks.ts, and related helpers indicate tasks are assembled from configuration rather than hardcoded page logic.
- This is reinforced by the README’s emphasis on customizable task order, repetitions, phonemes, topics, and other study parameters.
8. Client-side capture and analysis is a major boundary
- The browser is not just presenting forms; it also performs interactive capture:
- audio recording
- video recording
- microphone checks
- VAD-related logic
- playback and recording timers
- Hooks like useVoiceRecorder, useVideoRecorder, useVADLogic, and useWakeLock show that the participant experience relies heavily on in-browser media APIs.
- Public assets include voice instructions, illustrations, and ONNX/WASM VAD models, so some media intelligence happens locally in the client.
9. Frontend application structure and state boundaries
- Global state is organized through React contexts:
- UserContext
- ProtocolContext
- MappingContext
- TaskAudioContext
- AppProvider
- This indicates a layered client architecture where shared study/session state is lifted above individual screens.
- Dedicated page components separate major flows: login/auth, onboarding, participant interface, admin dashboard, project dashboard, protocol editor, and fieldwork.
10. API integration boundary
- The frontend has a matching API wrapper layer in frontend/src/api for the same domain resources exposed by the backend.
- This creates a clear separation:
- UI components call frontend API modules
- API modules call backend routes
- backend controllers persist to DB
- The pairing of route names and API modules suggests the system is designed around stable resource-based contracts.
11. Infrastructure and operational helpers
- The backend includes operational utilities for:
- email delivery
- token generation
- assignment logic
- SQL file execution
- logging
- date formatting
- The README’s SMTP settings imply outbound email is used for token or password-related flows.
- backend/hash_gen.js and backend/src/runInit.js show that first-time setup and credential seeding are part of the architecture, not ad hoc manual steps.
12. Localization and content delivery
- The frontend supports multiple languages (en, cs, de) through its i18n directory and translation utilities.
- Task instructions, admin text, and common UI strings are localized.
- Audio instructions and task illustration assets are served from public, which means task content is partly delivered as static media rather than fetched dynamically.
13. Data lifecycle in the system
- Study configuration enters through admin pages.
- It is stored in the database via backend CRUD endpoints.
- Participant assignment links users/participants to protocols and projects.
- During execution, the browser captures recordings and task outcomes.
- Results are written back to the backend and become visible in dashboards and fieldwork views.
14. Deployment and environment
- The project is intended for separate frontend and backend runtime processes during development.
- Vite serves the frontend; the backend serves API traffic.
- A GitHub Actions workflow exists for deployment, indicating CI/CD is part of the repo’s operational model.
- Environment files define the API base URL, DB connection, upload/data paths, and SMTP settings, so deployment depends on both database and mail configuration.
15. Good diagram boundaries to draw
- Draw three main zones:
- Browser client with participant UI, admin UI, local media capture, i18n, and task orchestration.
- Node API server with route/controller layers, auth, study management, recording/result ingestion, email/token services.
- MariaDB/MySQL database with schema, seed data, and study entities.
- Add external dependencies only where relevant: SMTP for email and browser media/VAD assets for client-side task execution.
Main entry points: App.jsx Frontend app · ParticipantInterfacePage.jsx Participant flow · server.js Server entry · projectController.js Domain controllers
Components 18
Browser client
React/Vite application for participants and administrators
- Frontend app · Browser application shell and routing
frontend/src/App.jsx - Participant flow · Auth, onboarding, and protocol execution screens
frontend/src/pages/ParticipantInterfacePage.jsx - Admin console · Dashboards for projects, protocols, participants, and fieldwork
frontend/src/pages/AdminDashboardPage.jsx - Protocol editor · Builds and edits protocol/task sequences
frontend/src/components/ProtocolEditor/ProtocolEditor.jsx - Task system · Task resolution, layouts, and task-specific components
frontend/src/config/tasksBase.ts - Media capture · Audio/video recording, mic checks, VAD, and wake lock
frontend/src/hooks/useVoiceRecorder.js - Client state · Shared user, protocol, mapping, and task audio state
frontend/src/context/AppProvider.jsx - API client · Typed resource wrappers for backend endpoints
frontend/src/api/auth.js - Localized assets · Translations, voice instructions, illustrations, and VAD models
frontend/src/i18n/index.js
Node API server
Express-style backend with routes, controllers, and services
- Server entry · Backend process bootstrap and HTTP server
backend/server.js - HTTP routes · Resource endpoints for auth, users, projects, protocols, participants, sessions, recordings, results, and mappings
backend/src/routes/auth.js - Domain controllers · Business actions for study resources and result ingestion
backend/src/controllers/projectController.js - Backend services · Email, tokens, assignment logic, logging, and SQL execution helpers
backend/src/utils/emailService.js - DB access · Connection and query helpers for relational persistence
backend/src/db/connection.js
Data and ops
Database, SQL initialization, email, and deployment support
Connections 21
- Frontend app → Participant flow: renders · Application routes participant-facing screens
- Frontend app → Admin console: renders · Application routes admin screens
- Frontend app → Protocol editor: renders · Protocol configuration workspace
- Participant flow → Task system: uses · Protocol-defined tasks and layouts
- Participant flow → Media capture: captures · Audio/video recording and mic/VAD flow
- Participant flow → Client state: shares state · User, protocol, and task session state
- Admin console → Client state: shares state · Dashboard and management data
- Protocol editor → Task system: configures · Builds task sequences and parameters
- Task system → Localized assets: loads · Localized instructions and media assets
- Frontend app → API client: calls · Browser requests to backend resources
- API client → HTTP routes: requests · Resource-based API contract
- Server entry → HTTP routes: mounts · HTTP endpoint registration
- HTTP routes → Domain controllers: delegates · Transport boundary to business logic
- Domain controllers → DB access: queries · Reads and writes persistent study data
- Domain controllers → Backend services: uses · Email, tokens, assignment, logging, SQL helpers
- DB access → MariaDB: persists to · Relational storage
- SQL init → MariaDB: creates · Schema, views, and seed data
- Backend services → SMTP mail: sends · Outbound mail delivery
- Server entry → CI deploy: deployed by · CI/CD workflow
- Server entry → SQL init: initialized by · First-run setup and SQL execution
- Frontend app → Server entry: consumes · Frontend talks to the API server