Deep Work Study Tracker 🎯

Deep Work Study Tracker is a full-stack web application designed as a productivity assistant to manage deep work sessions and track preparation progress for various study goals (e.g., ISTQB CTFL, JLPT N4, or technical mastery).

This application implements an internal Role-Based Access Control (RBAC) scheme, token-based authentication protection utilizing PASETO, and integrates an autonomous AI agent (OpenClaw) to dynamically generate study roadmaps and evaluation quizzes.

Beyond its product functionality, this project is specifically developed as an Advanced QA Engineer Portfolio, demonstrating the implementation of a comprehensive testing ecosystem encompassing Unit, Integration, E2E, Contract Testing for AI, and Security Testing.

---

Table of Contents

1. Objectives & Success Metrics
2. System Architecture & Tech Stack
3. User Roles & Access Control
4. Database Architecture (ERD)
5. Epics & User Stories
6. QA & Testing Strategy
7. Future Enhancements (v2.0)
8. Getting Started

---

1. Objectives & Success Metrics

1.1. Product Objectives (MVP)

• Provide an isolated and private study tracking platform with no public registration features (invite-only / Admin-managed).
• Allow users to securely manage their own credentials after account provisioning.
• Deliver a Pomodoro timer with robust, persistent state management.
• Present an analytics dashboard (heatmap & charts) to monitor daily consistency.
• Utilize AI to break down study syllabi into actionable items and evaluate learning materials.

1.2. Engineering & QA Objectives

• Achieve backend Test Coverage above 80%.
• Demonstrate strict authorization testing (RBAC) on every API endpoint.
• Implement efficient AI response Mocking in the CI/CD pipeline.
• Self-host deployment utilizing a Homelab architecture (Docker + Cloudflare Tunnel).

---

2. System Architecture & Tech Stack

• Frontend: React.js (Vite), Tailwind CSS, Zustand/Redux.
• Backend: Python (FastAPI) - Chosen for optimal AI integration and async capabilities.
• Database: PostgreSQL (Relational data & JSONB for AI responses).
• AI Engine: OpenClaw (via Webhook/API).
• Security & Authentication: * OAuth2 Password Bearer
  • PASETO (Platform-Agnostic Security Tokens)
  • bcrypt for password hashing.
• Infrastructure: Docker, Cloudflare Tunnel.

---

3. User Roles & Access Control

The system enforces strict access control divided into two main roles:

1. Admin (role: admin): Has full access to the Admin Dashboard to manage the user lifecycle (Create, Delete, Reset Password). Admins do not have a personal study dashboard within this interface.
2. User (role: user): End-users whose credentials are provisioned by the Admin. They can change their own passwords and have exclusive access to their own isolated study dashboard (Study Targets, Timer, Analytics, AI Tutor). Cannot access user management endpoints.

---

4. Database Architecture (ERD)

The database utilizes PostgreSQL, leveraging UUID for security and JSONB for handling dynamic AI data contracts efficiently.

[Image of database entity relationship diagram]

erDiagram
    USERS ||--o{ STUDY_TARGETS : "manages"
    STUDY_TARGETS ||--o{ STUDY_SESSIONS : "records"
    STUDY_TARGETS ||--o{ AI_ROADMAPS : "has"
    STUDY_SESSIONS ||--o{ AI_QUIZZES : "evaluates"

    USERS {
        uuid id PK
        string username UK
        string password_hash
        string role "Enum: 'admin', 'user'"
        timestamp created_at
        timestamp updated_at
    }

    STUDY_TARGETS {
        uuid id PK
        uuid user_id FK
        string title "e.g., 'ISTQB', 'Python Mastery'"
        date deadline_date
        timestamp created_at
    }

    STUDY_SESSIONS {
        uuid id PK
        uuid target_id FK
        int duration_minutes "e.g., 25, 60"
        date session_date "Used for heatmap query"
        timestamp created_at
    }

    AI_ROADMAPS {
        uuid id PK
        uuid target_id FK
        jsonb roadmap_data "Dynamic syllabus from OpenClaw"
        timestamp created_at
    }

    AI_QUIZZES {
        uuid id PK
        uuid session_id FK
        jsonb quiz_data "Questions and answer keys"
        int score "Nullable until completed"
        timestamp created_at
    }

Loading

---

5. Epics & User Stories (Acceptance Criteria)

Epic 1: Authentication & Security

• User Story 1 (Login): As a system user, I want to log in securely so that my study session data remains private.
  • AC: No public Sign Up page. Successful login returns a PASETO access token. Accessing protected endpoints without a valid PASETO token returns HTTP 401 Unauthorized.
• User Story 2 (Change Password): As a User, I want to change my own password securely to secure my account after Admin provisioning.
  • AC: System requires current_password, new_password, and confirm_new_password. Passwords are saved in a hashed format (bcrypt).

Epic 2: Admin Dashboard (User Management)

• User Story: As an Admin, I want to create and manage User accounts so I can control who has access.
  • AC: An interface exists for user CRUD operations. The API aggressively rejects requests with an HTTP 403 Forbidden if accessed using a token with role: user.

Epic 3: Study Target Management

• User Story: As a User, I want to create study targets along with their deadlines to track my remaining study time.
  • AC: Target data is exclusively tied to the logged-in user_id. System displays an accurate countdown timer.

Epic 4: Deep Work Timer

• User Story: As a User, I want to run a Pomodoro timer connected to a specific study target to record my focus duration.
  • AC: The running time state is persistent across browser refreshes. Stopped durations are saved to the database.

Epic 5: Analytics & Habit Tracking

• User Story: As a User, I want to see my daily contribution heatmap so I stay motivated.
  • AC: The dashboard displays a 365-day heatmap. Color intensity represents the accumulation of daily study minutes.

Epic 6: AI Tutor Integration (OpenClaw)

• User Story: As a User, I want AI to structure my syllabus and create evaluation quizzes.
  • AC: JSON responses from AI undergo strict schema validation and are saved using the JSONB data type. The UI renders the quiz and saves the score.

---

6. QA & Testing Strategy

As a QA-focused repository, testing is implemented across multiple layers:

1. UI E2E & Regression (Playwright + Pytest): Authentication, protected-route guard behavior, dashboard target lifecycle, timer async generation and polling behavior.
2. BDD Coverage (pytest-bdd): Authentication scenarios are mirrored in Gherkin + step definitions, using existing page objects.
3. API Automation (HTTPX Async + Pytest): Target CRUD lifecycle, async generation trigger/polling flows, negative failure-path behavior.
4. Schema/Contract Validation (Pydantic): API response models are validated against strict schemas in test layer.
5. Performance Baseline (k6): Concurrent trigger + polling simulation for async generation endpoint.

6.0. Current Test Layout (2026-03)

• Backend automation suites: backend/tests
• Frontend UI/BDD suites: frontend/test
• Optional local virtualenv for test tooling: tests/venv

Note: earlier docs and commands may reference legacy tests/* paths; use the paths above as source of truth.

6.1. Portfolio Test Reports

• UI HTML report: frontend/test/reports/portfolio_test_report.html
• API HTML report: backend/tests/reports/portfolio_api_report.html
• Portfolio landing page: backend/tests/reports/portfolio_index.html

Generate reports from project root:

./scripts/run_ui_report.sh
./scripts/run_api_report.sh
./scripts/run_all_reports.sh

---

7. Future Enhancements (v2.0)

To further elevate the platform from a tracking tool to a fully Adaptive Learning System, the following features are slated for v2.0:

• Adaptive AI Pre-Test Evaluation: Before generating a study roadmap, the system will prompt the user to take a dynamic pre-test generated by OpenClaw. The backend will evaluate the score and send a chained prompt to adjust the syllabus dynamically (e.g., skipping basic modules if the score is high).
• Gamification & Deep Work Leaderboard: Introducing a point-based system derived from consistent heatmap streaks to foster healthy competition among internal users.

---

8. Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL
• Docker (for isolated environment testing)

Local Setup

1. Backend Navigate to the /backend directory and configure your environment:

# Set up virtual environment and install dependencies
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure your environment variables (.env)
# Needs DATABASE_URL, SECRET_KEY, and OPENCLAW_API_KEY configurations

# Run database migrations
cd app
alembic upgrade head

# Start the FastAPI server
uvicorn main:app --reload

2. Frontend Navigate to the /frontend directory and set up the React client:

1. Create a .env file and configure the Backend API URL:

   VITE_API_URL=http://localhost:8000/api/v1

2. Install dependencies and run the client:

   npm install
   npm run dev

Built-in Guide: Once the application is running, log in and check the newly integrated "How to Use" page in the sidebar for a visual walkthrough of the Pomodoro-to-AI-Quiz learning loop.

Testing Quick Start:

# UI suite
tests/venv/bin/pytest frontend/test/ui/features frontend/test/ui/steps -q -rs

# API suite
tests/venv/bin/pytest backend/tests/api/ -q -rs

---

Authored by fanfanmyid | 2026