calebe20/estudopro

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.