# maskopav/task_protocoller_web_app architecture

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

- Interactive diagram: https://gitdiagram.com/maskopav/task_protocoller_web_app
- Repository: https://github.com/maskopav/task_protocoller_web_app

## Overview

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: [`frontend/src/App.jsx`](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/App.jsx) (Frontend app), [`frontend/src/pages/ParticipantInterfacePage.jsx`](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/pages/ParticipantInterfacePage.jsx) (Participant flow), [`backend/server.js`](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/server.js) (Server entry), [`backend/src/controllers/projectController.js`](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/controllers/projectController.js) (Domain controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_frontend_app["Frontend app<br/>React/Vite SPA<br/>[App.jsx]"]
  node_participant_ui["Participant flow<br/>study UI"]
  node_admin_ui["Admin console<br/>management UI"]
  node_protocol_editor["Protocol editor<br/>config UI<br/>[ProtocolEditor.jsx]"]
  node_task_engine["Task system<br/>task config<br/>[tasksBase.ts]"]
  node_media_capture["Media capture<br/>browser capture"]
  node_client_state["Client state<br/>React context<br/>[AppProvider.jsx]"]
  node_api_client["API client<br/>frontend API<br/>[auth.js]"]
  node_i18n_assets["Localized assets<br/>content/assets<br/>[index.js]"]
end

subgraph group_api["Node API server"]
  node_backend_server["Server entry<br/>Node.js API<br/>[server.js]"]
  node_http_routes["HTTP routes<br/>route layer<br/>[auth.js]"]
  node_domain_ctrls["Domain controllers<br/>controller layer"]
  node_backend_services["Backend services<br/>utility/service layer<br/>[emailService.js]"]
  node_db_access["DB access<br/>query layer<br/>[connection.js]"]
end

subgraph group_data["Data and ops"]
  node_db_init["SQL init<br/>schema/seed scripts<br/>[create_tables.sql]"]
  node_database[("MariaDB<br/>relational DB")]
  node_smtp(("SMTP mail<br/>external service"))
  node_deploy["CI deploy<br/>GitHub Actions<br/>[deploy.yml]"]
end

node_frontend_app -->|"renders"| node_participant_ui
node_frontend_app -->|"renders"| node_admin_ui
node_frontend_app -->|"renders"| node_protocol_editor
node_participant_ui -->|"uses"| node_task_engine
node_participant_ui -->|"captures"| node_media_capture
node_participant_ui -->|"shares state"| node_client_state
node_admin_ui -->|"shares state"| node_client_state
node_protocol_editor -->|"configures"| node_task_engine
node_task_engine -->|"loads"| node_i18n_assets
node_frontend_app -->|"calls"| node_api_client
node_api_client -->|"requests"| node_http_routes
node_backend_server -->|"mounts"| node_http_routes
node_http_routes -->|"delegates"| node_domain_ctrls
node_domain_ctrls -->|"queries"| node_db_access
node_domain_ctrls -->|"uses"| node_backend_services
node_db_access -->|"persists to"| node_database
node_db_init -->|"creates"| node_database
node_backend_services -->|"sends"| node_smtp
node_backend_server -.->|"deployed by"| node_deploy
node_backend_server -.->|"initialized by"| node_db_init
node_frontend_app -->|"consumes"| node_backend_server

click node_frontend_app "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/App.jsx"
click node_participant_ui "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/pages/ParticipantInterfacePage.jsx"
click node_admin_ui "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/pages/AdminDashboardPage.jsx"
click node_protocol_editor "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/components/ProtocolEditor/ProtocolEditor.jsx"
click node_task_engine "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/config/tasksBase.ts"
click node_media_capture "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/hooks/useVoiceRecorder.js"
click node_client_state "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/context/AppProvider.jsx"
click node_api_client "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/api/auth.js"
click node_i18n_assets "https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/i18n/index.js"
click node_backend_server "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/server.js"
click node_http_routes "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/routes/auth.js"
click node_domain_ctrls "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/controllers/projectController.js"
click node_backend_services "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/utils/emailService.js"
click node_db_access "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/db/connection.js"
click node_db_init "https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/scripts/schema/create_tables.sql"
click node_deploy "https://github.com/maskopav/task_protocoller_web_app/blob/main/.github/workflows/deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_participant_ui,node_admin_ui,node_protocol_editor,node_task_engine,node_media_capture,node_client_state,node_api_client,node_i18n_assets toneBlue
class node_backend_server,node_http_routes,node_domain_ctrls,node_backend_services,node_db_access toneAmber
class node_db_init,node_database,node_smtp,node_deploy toneMint
```

## Components

### Browser client

React/Vite application for participants and administrators

- [Frontend app](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/App.jsx): React/Vite SPA · Browser application shell and routing · `frontend/src/App.jsx`
- [Participant flow](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/pages/ParticipantInterfacePage.jsx): study UI · Auth, onboarding, and protocol execution screens · `frontend/src/pages/ParticipantInterfacePage.jsx`
- [Admin console](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/pages/AdminDashboardPage.jsx): management UI · Dashboards for projects, protocols, participants, and fieldwork · `frontend/src/pages/AdminDashboardPage.jsx`
- [Protocol editor](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/components/ProtocolEditor/ProtocolEditor.jsx): config UI · Builds and edits protocol/task sequences · `frontend/src/components/ProtocolEditor/ProtocolEditor.jsx`
- [Task system](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/config/tasksBase.ts): task config · Task resolution, layouts, and task-specific components · `frontend/src/config/tasksBase.ts`
- [Media capture](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/hooks/useVoiceRecorder.js): browser capture · Audio/video recording, mic checks, VAD, and wake lock · `frontend/src/hooks/useVoiceRecorder.js`
- [Client state](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/context/AppProvider.jsx): React context · Shared user, protocol, mapping, and task audio state · `frontend/src/context/AppProvider.jsx`
- [API client](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/api/auth.js): frontend API · Typed resource wrappers for backend endpoints · `frontend/src/api/auth.js`
- [Localized assets](https://github.com/maskopav/task_protocoller_web_app/blob/main/frontend/src/i18n/index.js): content/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](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/server.js): Node.js API · Backend process bootstrap and HTTP server · `backend/server.js`
- [HTTP routes](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/routes/auth.js): route layer · Resource endpoints for auth, users, projects, protocols, participants, sessions, recordings, results, and mappings · `backend/src/routes/auth.js`
- [Domain controllers](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/controllers/projectController.js): controller layer · Business actions for study resources and result ingestion · `backend/src/controllers/projectController.js`
- [Backend services](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/utils/emailService.js): utility/service layer · Email, tokens, assignment logic, logging, and SQL execution helpers · `backend/src/utils/emailService.js`
- [DB access](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/src/db/connection.js): query layer · Connection and query helpers for relational persistence · `backend/src/db/connection.js`

### Data and ops

Database, SQL initialization, email, and deployment support

- [SQL init](https://github.com/maskopav/task_protocoller_web_app/blob/main/backend/scripts/schema/create_tables.sql): schema/seed scripts · Table creation, views, seed data, and maintenance SQL · `backend/scripts/schema/create_tables.sql`
- **MariaDB**: relational DB · Persistent study data store
- **SMTP mail**: external service · Outbound email delivery for auth and study workflows
- [CI deploy](https://github.com/maskopav/task_protocoller_web_app/blob/main/.github/workflows/deploy.yml): GitHub Actions · Automated deployment workflow · `.github/workflows/deploy.yml`

## Connections

- 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