How clr4takeoff/fintune works
1. Repository type and runtime boundary
- This is a single-page React application built with TypeScript + Vite and deployed as a static front end.
- There is no custom backend server in the repo; persistence is handled either through Firebase Firestore or a browser localStorage fallback when Firebase is not configured.
2. Primary product flow
- The app is an experiment platform for a Prolific study on AI reliance and confidence calibration.
- The user journey is route-driven and follows the research protocol: register → login → screening → practice → experiment → result → result report → post survey → completion.
- These steps are implemented as separate page components under src/pages/, which makes the route sequence a central architectural boundary.
3. Application shell and navigation
- src/main.tsx boots the React app, and src/App.tsx likely owns the route composition and top-level navigation logic.
- src/layouts/ExperimentLayout.tsx provides the shared frame for the trial experience, separating experiment UI chrome from the page-specific content.
- The route structure is important because several pages are not independent screens but checkpoints in a controlled experimental flow.
4. State management layer
- The app uses Zustand stores in src/stores/ for client-side experiment state.
- participantStore appears to hold participant identity, condition assignment, validity, and screening metadata.
- experimentStore likely holds trial progression, current responses, timing, and report-related state.
- This creates a clear split between participant lifecycle state and in-experiment session state.
5. Participant lifecycle and validation
- src/services/participantService.ts and src/services/participantDB.ts manage participant creation, lookup, persistence, and likely fallback behavior.
- The participant record includes Prolific-facing identity, condition assignment, literacy score, and completion timestamps.
- The screening page acts as a gate before practice/experiment, so participant validity is part of the architectural control flow, not just data storage.
6. Trial generation and experimental content
- src/services/trialGenerationService.ts is the content-generation boundary for the experiment.
- The app consumes a static dataset from public/data/sampling_data.json, which contains the company finance records used to build trials.
- This service is responsible for producing the trial sequence, likely splitting practice trials and main experiment trials, and ensuring condition-dependent presentation.
7. Condition-specific behavior
- The experiment has three conditions:
- A: AI recommendation only
- B: AI recommendation + confidence display
- C: AI recommendation + confidence + interactive What-If slider
- This condition switch is a major architectural axis because it changes what the trial UI renders and what events are recorded.
- In practice, the trial pages need to branch on condition to decide whether confidence visualization and slider interaction are available.
8. AI prediction and What-If simulation
- The README indicates the AI logic is an inline logistic regression model on the frontend.
- That model is used for real-time prediction updates in the What-If flow, so the app does not depend on a server round-trip for AI feedback.
- This is a key boundary: the “AI” is a client-side simulation engine, not an external inference service.
9. Persistence model
- When Firebase is available, data goes to Firestore using the schema described in the README:
- participants/{participant_id}
- participants/{participant_id}/trials/{trial_id}
- participants/{participant_id}/trials/{trial_id}/slider_logs/{log_id}
- participants/{participant_id}/post_survey/{question_id}
- When Firebase is unavailable, the same logical data is kept in localStorage, which means the app is designed to run in a fully offline/developer mode as well.
- firebase.json, firestore.rules, and firestore.indexes.json show that Firebase hosting and Firestore access control are part of the deployment architecture.
10. Experiment telemetry and event granularity
- Trial response data is recorded at multiple levels: initial judgment, final judgment, confidence, switch status, response time, correctness, and reliance classification.
- Condition C adds fine-grained slider logs with before/after values and timestamps, which are stored separately from the trial summary.
- This separation suggests a reporting pipeline where trial outcomes and interaction traces are distinct analytical datasets.
11. Reporting and feedback outputs
- ResultPage and ResultReportPage split immediate per-trial feedback from the aggregated experiment summary.
- This indicates two different presentation layers: one for trial-level outcome feedback and another for study-level calibration/reporting.
- The post-survey page collects qualitative and Likert-scale data after the main task, and complete marks the terminal state of the study flow.
12. Models and shared types
- src/models/Participant.ts contains the core domain types used across services, stores, and pages.
- The repo likely centralizes participant/trial schema here so Firestore documents, UI state, and generated trial objects stay aligned.
- This model layer is small but important because it defines the contract between experiment content generation, UI state, and persistence.
13. Operational/tooling boundary
- The project is configured for a modern frontend toolchain: Vite, React 19, TypeScript, ESLint, and npm-based builds.
- makefile, package-lock.json, and Firebase config files indicate the repo is intended to be reproducibly built and deployed, but the architecture remains client-centric.
14. How to draw the architecture
- The cleanest diagram is: browser SPA at the center, with:
- routed pages on the UI side,
- Zustand stores as shared in-memory state,
- services for participant persistence, trial generation, and AI simulation,
- static dataset input from public/data/sampling_data.json,
- and Firestore/localStorage as the persistence layer.
- The most important cross-cutting control variable is the experiment condition, because it determines the UI, the interactions collected, and the data written.
Main entry points: App.tsx App · participantStore.ts Participant store · ExperimentPage.tsx Experiment · trialGenerationService.ts Trial generation
Components 21
React app
Browser SPA, routed pages, and shared layout.
- main.tsx · React entrypoint that mounts the app.
src/main.tsx - App · Top-level route composition and navigation flow.
src/App.tsx - Experiment layout · Shared experiment frame around trial screens.
src/layouts/ExperimentLayout.tsx - Register · Participant registration step.
src/pages/RegisterPage.tsx - Login · Participant login / lookup step.
src/pages/LoginPage.tsx - Condition select · Assigns or confirms experiment condition.
src/pages/ConditionSelectPage.tsx - Screening · Validity gate before the task flow.
src/pages/ScreeningPage.tsx - Practice · Practice trials before the main experiment.
src/pages/PracticePage.tsx - Experiment · Main trial task and response capture.
src/pages/ExperimentPage.tsx - Result · Immediate per-trial feedback screen.
src/pages/ResultPage.tsx - Report · Aggregated calibration and study summary.
src/pages/ResultReportPage.tsx - Post survey · Likert and free-response questionnaire.
src/pages/PostSurveyPage.tsx - Complete · Terminal completion screen.
src/pages/CompletePage.tsx
Client state
In-memory experiment and participant state.
- Participant store · Participant identity, condition, validity, and screening metadata.
src/stores/participantStore.ts - Experiment store · Trial progression, responses, timing, and report state.
src/stores/experimentStore.ts
Services
Experiment logic, persistence orchestration, and AI simulation.
- Trial generation · Builds practice and main trials from study data and condition.
src/services/trialGenerationService.ts - Participant service · Creates, loads, validates, and saves participant records.
src/services/participantService.ts - Participant DB · Persistence boundary with Firestore or localStorage fallback.
src/services/participantDB.ts
Data
Static input and domain models.
- Participant model · Shared participant and trial contracts.
src/models/Participant.ts - Sampling data · Company finance records used to generate trials.
public/data/sampling_data.json
Deployment
Firebase and build/runtime configuration.
- Firebase · Firestore initialization and environment integration.
src/services/firebase.ts
Connections 28
- main.tsx → App: mounts · Bootstraps the routed React application.
- App → Register: routes · Defines the registration step.
- App → Login: routes · Defines the login step.
- App → Condition select: routes · Defines condition selection.
- App → Screening: routes · Defines the screening gate.
- App → Practice: routes · Defines practice flow.
- App → Experiment: routes · Defines main trial flow.
- App → Result: routes · Defines trial feedback.
- App → Report: routes · Defines summary reporting.
- App → Post survey: routes · Defines post-study survey.
- App → Complete: routes · Defines terminal completion state.
- Experiment → Experiment layout: uses · Renders within the shared experiment shell.
- Register → Participant store: updates · Creates participant state.
- Login → Participant store: loads · Restores participant state.
- Condition select → Participant store: assigns · Sets experimental condition.
- Screening → Participant store: validates · Sets eligibility and screening metadata.
- Practice → Experiment store: advances · Seeds practice progression and responses.
- Experiment → Experiment store: records · Stores trial state and telemetry.
- Result → Experiment store: reads · Consumes trial outcome state.
- Report → Experiment store: reads · Aggregates experiment outcomes.
- Post survey → Participant service: saves · Persists post-survey and completion data.
- Participant service → Participant DB: uses · Delegates storage operations.
- Participant DB → Firebase: prefers · Uses Firestore when configured.
- Participant DB → Participant store: serializes · Maps domain records to stored participant data.
- Trial generation → Sampling data: consumes · Builds trials from the static dataset.
- Practice → Trial generation: builds · Generates practice trials.
- Experiment → Trial generation: builds · Generates main experiment trials.
- Trial generation → Participant store: depends on · Uses participant condition and validity.