FocusAid

FocusAid is a productivity and focus-management app aimed at people with ADHD / attention challenges. It combines task management, mood-adaptive prioritization, Pomodoro focus tracking, gamified rewards, notifications, AI-assisted task breakdown, and speech-to-text task capture — backed by a FastAPI service and an Expo/React Native mobile client.

Presentation   React Native (Expo) mobile app
State/Domain   Redux Toolkit slices mirroring backend entities (tasks, moods, rewards, pomodoro, notifications)
Transport      REST over HTTPS (FastAPI), JSON, JWT auth
Business Logic Prioritization engine + gamification (badges/XP/streaks) + AI-assisted task decomposition
Data           PostgreSQL via SQLAlchemy models + Alembic migrations
Intelligence   External Gemma inference endpoint + AssemblyAI speech-to-text

Repository layout

backend/focusaid-backend/   FastAPI + SQLAlchemy + PostgreSQL API
  app/
    main.py                  App setup, router registration
    config.py                Env-driven configuration
    database.py              SQLAlchemy engine/session, get_db dependency
    models/                  SQLAlchemy models (user, task, subtask, mood, pomodoro, reward, notification)
    schemas/                 Pydantic request/response schemas
    routes/                  Feature routers (auth, tasks, moods, pomodoro, rewards, notifications, ai, speech)
    utils/                   Auth, gamification, prioritization helpers
    tests/                   Pytest suite
  alembic/                   Database migrations
  postman/                   Postman collection, environment, and generated test reports
  docs/                      Backend docs: API reference, per-model/per-route docs, presentations
  requirements.txt, run.py, alembic.ini

frontend/FocusAid/           Expo / React Native mobile app
  src/
    api/                      Axios instance + API calls
    redux/                    Store + slices (auth, tasks, moods, pomodoro, rewards, notifications, preferences)
    navigation/                Stack/tab navigators
    screens/                   Feature screens (auth/, main/, mood/, tasks/, rewards/, education/, onboarding/, ...)
    components/                Reusable UI, incl. analytics/, forms/, rewards/, help/
    hooks/, theme/, utils/, constants/, assets/
  docs/                       Frontend docs: app info, feature catalog, test reports
  App.js, index.js, app.json, eas.json, package.json

docs/report/                 Written project report, in reading order (00 → 06):
                              overview, tools & technologies, design methodology,
                              system design & implementation, diagrams, implementation,
                              screens, testing & results

Tech stack

Layer	Technology
Mobile framework	React Native 0.79 + Expo SDK 53, React 19
Mobile state	Redux Toolkit + react-redux
Mobile navigation	React Navigation (stack + bottom tabs)
Mobile networking	Axios
Mobile extras	Lottie animations, expo-notifications, expo-secure-store, expo-speech, react-native-calendars, xlsx export
API framework	FastAPI 0.115
ORM / DB	SQLAlchemy 2.0 + PostgreSQL (Neon), Alembic migrations
Auth	JWT (python-jose) + passlib[bcrypt] hashing
Validation	Pydantic v2
Speech-to-text	AssemblyAI
AI task breakdown	External Gemma inference endpoint (HTTP)
Backend testing	Pytest
API testing	Postman / Newman

Core features

• Auth & onboarding — JWT-based register/login with refresh tokens, secure on-device token storage.
• Tasks & subtasks — CRUD with priority, effort level, task type, deadlines; AI-assisted subtask generation.
• Mood-adaptive prioritization — daily mood logging influences task ordering via /tasks/prioritized.
• Pomodoro sessions — start/stop timers, persisted sessions feed analytics.
• Analytics & progress — focus time, session distribution, task completion/velocity, category breakdowns, exportable to PDF/CSV/XLSX.
• Gamification — badges, XP, levels, streaks; milestone checks run after task/subtask/pomodoro mutations.
• Notifications — scheduled + local reminders for sessions and tasks.
• Speech-to-text — capture tasks by voice via AssemblyAI, proxied server-side so the API key never reaches the client.
• Education content — in-app articles on focus/ADHD topics.

API surface (backend)

Router	Prefix	Purpose
auth	/auth	Register, login, token refresh
tasks	/tasks	CRUD tasks/subtasks, prioritization, AI subtask expansion
moods	/moods	Log and fetch moods
pomodoro	/pomodoro	Start/end/list focus sessions
rewards	/rewards	List/unlock badges, XP, streaks
notifications	/notifications	Schedule/list user notifications
ai	/ai	AI-assisted subtask breakdown
speech	/api/speech	AssemblyAI transcription (URL/file upload, status, result)

Full request/response docs: backend/focusaid-backend/docs/api-reference.md and per-route files under backend/focusaid-backend/docs/routes/.

Getting started

Prerequisites

• Python 3.11+
• Node.js 18+
• A PostgreSQL database (e.g. Neon) for the backend
• Expo Go app (or an Android/iOS emulator) to run the mobile client

1. Backend setup

cd backend/focusaid-backend
python -m venv .venv
. .venv/Scripts/Activate.ps1        # Windows PowerShell
# source .venv/bin/activate         # macOS/Linux

pip install -r requirements.txt
cp .env.example .env                # then fill in real values, see table below
python -m app.create_tables         # or: alembic upgrade head
python run.py                       # starts on http://localhost:8000

Backend environment variables (backend/focusaid-backend/.env):

Variable	Required	Description
DATABASE_URL	Yes	Primary Postgres connection string
TEST_DATABASE_URL	Yes (for tests)	Postgres connection string used by the test suite
JWT_SECRET	Yes	Secret used to sign JWTs
ASSEMBLYAI_API_KEY	For speech features	AssemblyAI API key
GEMMA_EXTERNAL_ENDPOINT	Optional	External LLM endpoint used for AI subtask generation

Run tests:

pytest -q

2. Frontend setup

cd frontend/FocusAid
npm install
cp .env.example .env                # then fill in real values, see table below
npx expo start

Then press a (Android), i (iOS), or w (web) in the Expo CLI, or scan the QR code with Expo Go.

Frontend environment variables (frontend/FocusAid/.env):

Variable	Description
API_BASE_URL	Base URL of the backend API (use your machine's LAN IP when testing on a physical device, e.g. http://192.168.x.x:8000)
WEATHER_API_URL	Weather API endpoint used by the home screen widget

Security note

.env files hold real credentials and are gitignored in this repo — never commit them. Use each project's .env.example as the template. Credentials that were previously committed to git history (Postgres password, JWT secret, AssemblyAI key) should be treated as compromised and rotated, regardless of the current .gitignore state.

Documentation index

Doc	Covers
backend/focusaid-backend/README.md	Backend setup, speech/AI endpoint notes, testing
backend/focusaid-backend/docs/	API reference, per-model & per-route specs, backend codebase guide, presentations, pytest test reports
frontend/FocusAid/README.md	Mobile app setup, project structure
frontend/FocusAid/docs/	App info, feature catalog
docs/report/	Full written project report (design methodology, system design, implementation, screens, testing & results)

Known gaps / roadmap

• No background scheduler (e.g. APScheduler/Celery) for sending notifications at their scheduled time.
• No rate limiting or abuse protection on the API.
• task_type is stored as a free string rather than an enum.
• Timezone handling is client-supplied (tz_offset) rather than stored per-user.
• Consider Dockerizing the backend for portability, and adding a generated API client for the frontend from the OpenAPI schema (/docs on the running backend).