# calebe20/estudopro architecture

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

- Interactive diagram: https://gitdiagram.com/calebe20/estudopro
- Repository: https://github.com/calebe20/estudopro

## Overview

1. **Project shape**
   EstudoPro is a study-management platform centered on exam prep workflows: adaptive question practice, flashcards, review history, performance dashboards, timers, goals, errors, and syllabus/cycle management. The repo is not a single-purpose app; it combines a large web application, Firebase-backed data services, background processing, and an Android shell.

2. **Primary runtime and app shell**
   The main product UI lives in `src/app` using the Next.js App Router pattern. Route groups under `src/app/(main)` map directly to major product areas such as `adaptive`, `flashcards`, `review`, `timer`, `dashboard`, `performance`, `errors`, `goals`, `syllabus`, `settings`, and `speedster`. Shared layout concerns sit in `src/components/layout`, with auth protection handled by `src/components/features/auth`.

3. **Feature-oriented UI structure**
   Most functionality is organized as feature modules under `src/components/features/*`. Each feature typically contains its own UI components, logic layer, service layer, and types. This gives a strong boundary between domains like flashcards, adaptive study, timer, review, performance, gamification, settings, and mobile. The route pages are mostly thin composition layers over these feature modules.

4. **Central state and persistence boundary**
   Application-wide state is coordinated through the store utilities in `src/utils/store`, with React contexts in `src/contexts` and store hooks/actions spread across `src/utils/store/*`. This layer handles persistence, import/export, backup/restore, cycle/subject/session state, and synchronization concerns. The store is the main boundary between user interactions and durable study data.

5. **Adaptive study engine**
   The adaptive subsystem is the most architecturally dense part of the repo. It spans:
   - UI: `src/components/features/adaptive`
   - Hooks/controllers: `src/hooks/adaptive`
   - Domain logic: `src/utils/adaptive`
   - Services/workers: `src/services/adaptive*`
   
   Its data flow is: material import and question-bank management → theme/subtheme structure → mastery scoring and scheduling → question selection/supply planning → session execution and progress tracking. This subsystem also includes question movement, import plans/results, coverage targets, support text, AI validation, and diagnostic export.

6. **AI-assisted generation and validation**
   AI is used mainly for adaptive question generation and flashcard/question text workflows. The repo references Gemini in the README via `GEMINI_API_KEY`, and the backend includes generation queues/workers plus services like `aiService`, `cardGeneratorService`, and adaptive question generation helpers. There are explicit validation and prompt-building utilities, indicating a controlled AI pipeline rather than direct UI-only prompting.

7. **Flashcards and review workflows**
   Flashcards are a separate study subsystem with its own service, logic, browser, creator/import modals, review session UI, and AI analysis tooling. Review uses its own service and logic layers and is backed by calendar/history views. Together they represent a second study loop distinct from adaptive questions, but they share persistence and study history data.

8. **Timer, sessions, and habit tracking**
   The timer subsystem includes Pomodoro logic, global timer behavior, weekly quests, history tracking, and multiple visualization components. It is tightly connected to study sessions and persistence, but architecturally separate from the adaptive engine. The timer also has mobile-specific views and an Android floating timer service, showing it is intended as a cross-platform productivity feature.

9. **Analytics and reporting surfaces**
   Dashboard, performance, accuracy, errors, medals, and goals are mostly read/aggregate surfaces. They consume stored study data and present trends, completion, rankings, consistency, error history, and progress indicators. These areas are split into presentation logic and calculation utilities in `src/utils/dashboard`, `src/utils/performance`, `src/utils/accuracy`, `src/utils/errors`, and `src/utils/masteryProgress`.

10. **Backend and server-side execution**
   There are two server-side entry points:
   - Next.js API routes in `src/app/api` for operations like backtesting and oracle analysis.
   - Firebase Cloud Functions in `functions/`, including `adaptiveQuestionWorker.js`.
   
   These backend pieces support asynchronous or heavier operations, while the main app remains the primary interaction layer. The presence of worker-like code suggests background generation or processing rather than only synchronous request/response behavior.

11. **Data platform and Firebase integration**
   The repository is strongly Firebase-oriented. It contains Firestore rules and indexes, Storage rules, Firebase hosting config, and a Dataconnect schema plus generated client packages under `src/dataconnect-generated`. There is also `src/lib/firebase/config.ts` and a Google Sheets integration layer, so the app’s data model is not purely local—it is backed by Firebase services and external sheet-based inputs.

12. **Mobile/native boundary**
   The `android/` directory is a Capacitor-based Android wrapper around the web app. Native code includes a floating timer service, overlay plugin, and the main activity, which suggests selected study features are elevated into native capabilities. The mobile UI also has dedicated components under `src/components/mobile`.

13. **Static assets, media, and model data**
   `public/` contains audio, images, medal assets, and ML-like JSON datasets. These assets feed UI polish, ambient sound features, and data-driven visualizations. The `public/ml-data` directory indicates some dashboards or gameplay-like features rely on precomputed model/config data rather than live remote inference.

14. **Quality, testing, and governance**
   The repo is heavily test-driven, with many targeted Vitest scripts covering adaptive logic, flashcards, dashboard behavior, persistence, timers, performance, and API routes. There are also Python and Node audit scripts plus documentation artifacts under `docs/` that appear to define product contracts and refactoring plans. The README explicitly points to `docs/CONSTITUICAO_ESTUDO_ADAPTATIVO.md` as the architectural source of truth for the adaptive domain.

Main entry points: [`src/utils/store`](https://github.com/calebe20/estudopro/tree/main/src/utils/store) (Store core), [`src/components/features`](https://github.com/calebe20/estudopro/tree/main/src/components/features) (Study modules), [`src/hooks/adaptive`](https://github.com/calebe20/estudopro/tree/main/src/hooks/adaptive) (Adaptive hooks), [`src/services`](https://github.com/calebe20/estudopro/tree/main/src/services) (Adaptive services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Web app"]
  node_node_main_routes["Main routes<br/>Next.js App Router"]
end

subgraph group_grp_features["Feature modules"]
  node_node_layout_auth["Layout auth<br/>UI shell"]
  node_node_feature_modules["Study modules<br/>Feature UI"]
  node_node_flashcards["Flashcards<br/>Study feature"]
  node_node_review["Review<br/>History feature"]
  node_node_timer["Timer<br/>Productivity feature"]
  node_node_performance["Performance<br/>Analytics feature"]
  node_node_settings_data["Data mgmt<br/>Settings feature"]
end

subgraph group_grp_core["Core state"]
  node_node_store["Store core<br/>State/persistence"]
  node_node_contexts["React contexts<br/>App state"]
  node_node_dashboard_utils["Analytics utils<br/>Calculation layer"]
end

subgraph group_grp_adaptive["Adaptive engine"]
  node_node_adaptive_ui["Adaptive UI<br/>Study UI"]
  node_node_adaptive_hooks["Adaptive hooks<br/>Controllers"]
  node_node_adaptive_domain["Adaptive domain<br/>Study logic"]
  node_node_adaptive_services["Adaptive services<br/>Workers/services"]
end

subgraph group_grp_data["Data platform"]
  node_node_api["API routes<br/>Next.js API"]
  node_node_functions["Cloud functions<br/>Firebase functions"]
  node_node_firebase[("Firebase data<br/>Firestore/Storage/Dataconnect<br/>[config.ts]")]
  node_node_assets["Assets<br/>Static media"]
end

subgraph group_grp_mobile["Mobile shell"]
  node_node_mobile["Android shell<br/>Capacitor app"]
  node_node_mobile_ui["Mobile UI<br/>Mobile feature"]
end

node_node_main_routes -->|"renders with"| node_node_layout_auth
node_node_main_routes -->|"composes"| node_node_feature_modules
node_node_layout_auth -->|"reads state"| node_node_store
node_node_feature_modules -->|"uses store"| node_node_store
node_node_feature_modules -->|"consumes"| node_node_contexts
node_node_adaptive_ui -->|"drives"| node_node_adaptive_hooks
node_node_adaptive_hooks -->|"orchestrates"| node_node_adaptive_domain
node_node_adaptive_hooks -->|"invokes"| node_node_adaptive_services
node_node_adaptive_domain -->|"persists via"| node_node_store
node_node_adaptive_services -->|"syncs with"| node_node_firebase
node_node_adaptive_services -->|"offloads"| node_node_functions
node_node_flashcards -->|"shares data"| node_node_store
node_node_review -->|"reads history"| node_node_store
node_node_timer -->|"records sessions"| node_node_store
node_node_performance -->|"calculates from"| node_node_dashboard_utils
node_node_performance -->|"aggregates data"| node_node_store
node_node_settings_data -->|"administers"| node_node_store
node_node_dashboard_utils -->|"derives from"| node_node_store
node_node_api -->|"serves"| node_node_firebase
node_node_mobile -->|"hosts"| node_node_mobile_ui
node_node_mobile_ui -->|"extends"| node_node_timer
node_node_mobile_ui -->|"syncs state"| node_node_store
node_node_assets -->|"feeds"| node_node_feature_modules

click node_node_main_routes "https://github.com/calebe20/estudopro/tree/main/src/app/(main)"
click node_node_layout_auth "https://github.com/calebe20/estudopro/tree/main/src/components/layout"
click node_node_feature_modules "https://github.com/calebe20/estudopro/tree/main/src/components/features"
click node_node_adaptive_ui "https://github.com/calebe20/estudopro/tree/main/src/components/features/adaptive"
click node_node_adaptive_hooks "https://github.com/calebe20/estudopro/tree/main/src/hooks/adaptive"
click node_node_adaptive_domain "https://github.com/calebe20/estudopro/tree/main/src/utils/adaptive"
click node_node_adaptive_services "https://github.com/calebe20/estudopro/tree/main/src/services"
click node_node_store "https://github.com/calebe20/estudopro/tree/main/src/utils/store"
click node_node_contexts "https://github.com/calebe20/estudopro/tree/main/src/contexts"
click node_node_flashcards "https://github.com/calebe20/estudopro/tree/main/src/components/features/flashcards"
click node_node_review "https://github.com/calebe20/estudopro/tree/main/src/components/features/review"
click node_node_timer "https://github.com/calebe20/estudopro/tree/main/src/components/features/timer"
click node_node_performance "https://github.com/calebe20/estudopro/tree/main/src/components/features/performance"
click node_node_settings_data "https://github.com/calebe20/estudopro/tree/main/src/components/features/settings/data-management"
click node_node_dashboard_utils "https://github.com/calebe20/estudopro/tree/main/src/utils"
click node_node_api "https://github.com/calebe20/estudopro/tree/main/src/app/api"
click node_node_functions "https://github.com/calebe20/estudopro/tree/main/functions"
click node_node_firebase "https://github.com/calebe20/estudopro/blob/main/src/lib/firebase/config.ts"
click node_node_mobile "https://github.com/calebe20/estudopro/tree/main/android"
click node_node_mobile_ui "https://github.com/calebe20/estudopro/tree/main/src/components/mobile"
click node_node_assets "https://github.com/calebe20/estudopro/tree/main/public"

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_node_main_routes toneBlue
class node_node_layout_auth,node_node_feature_modules,node_node_flashcards,node_node_review,node_node_timer,node_node_performance,node_node_settings_data toneAmber
class node_node_store,node_node_contexts,node_node_dashboard_utils toneMint
class node_node_adaptive_ui,node_node_adaptive_hooks,node_node_adaptive_domain,node_node_adaptive_services toneRose
class node_node_api,node_node_functions,node_node_firebase,node_node_assets toneIndigo
class node_node_mobile,node_node_mobile_ui toneTeal
```

## Components

### Web app

Next.js routes and page shells for the main product areas.

- [Main routes](https://github.com/calebe20/estudopro/tree/main/src/app/(main)): Next.js App Router · Route groups under src/app/(main) for study and analytics pages. · `src/app/(main)`

### Feature modules

Domain-oriented UI and feature logic reused by routes and mobile surfaces.

- [Layout auth](https://github.com/calebe20/estudopro/tree/main/src/components/layout): UI shell · Shared header/sidebar layout and route protection for the app shell. · `src/components/layout`
- [Study modules](https://github.com/calebe20/estudopro/tree/main/src/components/features): Feature UI · Feature-oriented modules for flashcards, review, timer, goals, performance, settings, and gamification. · `src/components/features`
- [Flashcards](https://github.com/calebe20/estudopro/tree/main/src/components/features/flashcards): Study feature · Flashcard browser, creator, review session, AI analysis, and import tooling. · `src/components/features/flashcards`
- [Review](https://github.com/calebe20/estudopro/tree/main/src/components/features/review): History feature · Review page, card forms, and calendar/history views backed by study records. · `src/components/features/review`
- [Timer](https://github.com/calebe20/estudopro/tree/main/src/components/features/timer): Productivity feature · Pomodoro timer, global timer logic, weekly quests, and timer history visualizations. · `src/components/features/timer`
- [Performance](https://github.com/calebe20/estudopro/tree/main/src/components/features/performance): Analytics feature · Performance dashboards, contest charts, ranking lists, and subject/topic summaries. · `src/components/features/performance`
- [Data mgmt](https://github.com/calebe20/estudopro/tree/main/src/components/features/settings/data-management): Settings feature · Settings, backup/restore, imports, question management, and study history administration. · `src/components/features/settings/data-management`

### Core state

Shared store, contexts, hooks, and persistence boundaries.

- [Store core](https://github.com/calebe20/estudopro/tree/main/src/utils/store): State/persistence · Global store, persistence, import/export, backup/restore, session, cycle, and subject/topic actions. · `src/utils/store`
- [React contexts](https://github.com/calebe20/estudopro/tree/main/src/contexts): App state · Context providers for confirmation and timer state. · `src/contexts`
- [Analytics utils](https://github.com/calebe20/estudopro/tree/main/src/utils): Calculation layer · Dashboard, performance, accuracy, errors, and mastery progress calculations. · `src/utils`

### Adaptive engine

The densest study subsystem: selection, mastery, import, AI, and session flow.

- [Adaptive UI](https://github.com/calebe20/estudopro/tree/main/src/components/features/adaptive): Study UI · Adaptive study page, session panels, bank browser, import/move dialogs, and support text tools. · `src/components/features/adaptive`
- [Adaptive hooks](https://github.com/calebe20/estudopro/tree/main/src/hooks/adaptive): Controllers · Hook layer coordinating bank actions, imports, maintenance, sessions, and supply worker access. · `src/hooks/adaptive`
- [Adaptive domain](https://github.com/calebe20/estudopro/tree/main/src/utils/adaptive): Study logic · Rules for mastery, scheduling, supply plans, selection, validation, imports, and diagnostic export. · `src/utils/adaptive`
- [Adaptive services](https://github.com/calebe20/estudopro/tree/main/src/services): Workers/services · Async services for question generation, imports, AI validation, canonical components, and lifecycle operations. · `src/services`

### Data platform

Firebase, Dataconnect, API routes, and background workers.

- [API routes](https://github.com/calebe20/estudopro/tree/main/src/app/api): Next.js API · Server routes for backtest and oracle analysis operations. · `src/app/api`
- [Cloud functions](https://github.com/calebe20/estudopro/tree/main/functions): Firebase functions · Background worker entry points for adaptive processing. · `functions`
- [Firebase data](https://github.com/calebe20/estudopro/blob/main/src/lib/firebase/config.ts): Firestore/Storage/Dataconnect · Firebase config, rules, indexes, Dataconnect schema, generated clients, and external sheet integration. · `src/lib/firebase/config.ts`
- [Assets](https://github.com/calebe20/estudopro/tree/main/public): Static media · Images, medals, sounds, and precomputed ML-like JSON data used by study and UI features. · `public`

### Mobile shell

Android wrapper and mobile-specific app behavior.

- [Android shell](https://github.com/calebe20/estudopro/tree/main/android): Capacitor app · Android wrapper with overlay plugin, floating timer service, and native activity. · `android`
- [Mobile UI](https://github.com/calebe20/estudopro/tree/main/src/components/mobile): Mobile feature · Mobile-specific question, timer, radio, settings, and session components. · `src/components/mobile`

## Connections

- Main routes → Layout auth: renders with · Pages share the main layout and auth boundary.
- Main routes → Study modules: composes · Route pages mostly delegate to feature modules.
- Layout auth → Store core: reads state · Layout and auth surfaces depend on persisted session/user state.
- Study modules → Store core: uses store · Feature modules read and write study data through the shared store.
- Study modules → React contexts: consumes · Some feature surfaces rely on shared React contexts.
- Adaptive UI → Adaptive hooks: drives · Adaptive UI is mostly a composition layer over adaptive hooks.
- Adaptive hooks → Adaptive domain: orchestrates · Hooks coordinate domain rules and state transitions.
- Adaptive hooks → Adaptive services: invokes · Hooks trigger imports, AI work, and background generation services.
- Adaptive domain → Store core: persists via · Mastery, scheduling, and bank state ultimately flow into the store.
- Adaptive services → Firebase data: syncs with · Services rely on Firebase-backed persistence and data exchange.
- Adaptive services → Cloud functions: offloads · Heavy adaptive generation can run in cloud function workers.
- Flashcards → Store core: shares data · Flashcards use the same durable study data boundary.
- Review → Store core: reads history · Review views are backed by persisted study records and history.
- Timer → Store core: records sessions · Timer and quest features write activity and session history.
- Performance → Analytics utils: calculates from · Analytics surfaces are driven by shared calculation utilities.
- Performance → Store core: aggregates data · Performance views consume stored study outcomes and rankings.
- Data mgmt → Store core: administers · Backup, restore, import, and cleanup operations target the store.
- Analytics utils → Store core: derives from · Calculation utilities consume persisted study and timer data.
- API routes → Firebase data: serves · API routes support server-side analysis on top of Firebase data.
- Android shell → Mobile UI: hosts · The Android wrapper exposes mobile-specific app screens.
- Mobile UI → Timer: extends · Mobile timer surfaces align with the web timer subsystem.
- Mobile UI → Store core: syncs state · Mobile interactions share the same study store boundary.
- Assets → Study modules: feeds · Media assets and ML datasets support feature rendering and study flows.