# Focus Better — Complete System & Architecture Specification

> Focus sessions and habits, without the noise. An offline-first productivity platform featuring event-sourced timers, atomic habit tracking, project milestone boards, and Mount Olympus expedition gamification.

Focus Better combines deep-work timers, habit consistency streaks, project execution, and non-intrusive gamification into a unified, high-performance web and desktop platform.

Website: https://app.focusbetter.io
API Endpoint: https://api.focusbetter.io/api/v1 (Interactive OpenAPI docs at /api/docs)

---

## 1. Product Loop: Projects → Focus → Habits

Focus Better structures productivity around a tight behavioral loop:

1. **Projects & Tasks**: Organize high-leverage initiatives, roadmaps, milestones, and actionable tasks.
2. **Focus Sessions**: Execute deep work on selected tasks using event-sourced Pomodoro or Flow timers with ambient audio.
3. **Habit Tracking**: Maintain recurring consistency habits that run independently of focus timers, with streaks, targets, and freeze protection.
4. **Mount Olympus Gamification**: Rewarding focused execution with Momentum XP, Summit Coins, level ascension, and expedition basecamps.

---

## 2. Core Modules & Capabilities

### Focus Sessions & Timers
- **Event-Sourced Architecture**: The server session record and append-only event log (`session_started`, `paused`, `resumed`, `completed`, `abandoned`) is the authoritative source of truth.
- **Client Timer**: Display-only countdown/elapsed calculation derived directly from event timestamps. Resilient to tab sleep, device locks, and clock skew.
- **Modes**:
  - Classic Pomodoro (25m focus / 5m break or customizable duration).
  - Open Flow (unbounded deep work with pause/resume capabilities).
- **Soundscapes**: Integrated ambient audio catalogs for white noise, binaural beats, rainfall, and coffee shop atmospheres.
- **Atomic Completion**: Completing a focus session updates task activity, releases gamification rewards, and records execution metrics idempotently.

### Atomic Habits
- **Independent Consistency**: Habits are independent of focus timers. Completing a focus session never checks off a habit automatically; habit completion is an intentional user check-in.
- **Schedules**: Daily, specific weekdays, or weekly target frequencies (e.g. 3x per week).
- **Streaks & Protection**: Current streak, best streak, and streak freeze protections that prevent streak resets during scheduled off-days or emergencies.

### Projects, Tasks & Roadmap
- **Portfolio Hierarchy**: Projects hold tasks, subtasks, tags, milestones, and ideas.
- **Workflow Statuses**: Customizable statuses (Backlog, Todo, In Progress, In Review, Done) scoped per project.
- **Kanban Roadmap**: Visual drag-and-drop workflow with collocated widget views on the dashboard.
- **Activity Feed**: Merged timeline of task creations, completions, milestone advancements, and focus hours.

### Mount Olympus Gamification
- **Philosophy**: Gamification serves as a quiet psychological tailwind, never intrusive noise.
- **Momentum Execution Score**: Daily dynamic score calculated from focus minutes and completed habit targets.
- **Mount Olympus Expedition**: 5 distinct basecamps representing mastery levels (Basecamp 1 through Summit).
- **Summit Coins**: Earned via daily milestone accomplishments and basecamp progress, spendable on customization perks and avatar rewards.
- **Idempotent Settlement**: Event-driven worker reconciles scores and achievements asynchronously; gamification never blocks user product writes.

### Calendar Sync
- **Google Calendar OAuth**: Two-way connection supporting read-only external calendar merging and projection of scheduled focus blocks.
- **Recurrence Engine**: Full iCalendar RRULE projection support for repeating focus sessions.

### Offline-First Data Engine
- **IndexedDB Action Queue**: Full offline support for timer state, habit check-ins, and task updates.
- **Optimistic UI**: Immediate UI response with background replay once connectivity is restored.
- **Idempotency**: All mutating operations carry unique UUID idempotency keys to ensure duplicate requests produce identical outcomes.

---

## 3. Technology Architecture & Stack

### Client Architecture
- **Framework**: Next.js 16 (App Router) + React 19.
- **Styling**: Tailwind CSS v4 design tokens + Motion for React animations.
- **State Management**: TanStack Query (React Query) for server state caching + durable IndexedDB offline queue.
- **Authentication**: NextAuth v5 with JWT bearer token handoff to the backend.
- **Hosting**: Vercel.

### Backend Services Architecture
- **Framework**: NestJS running on high-performance Fastify adapter.
- **Database**: PostgreSQL 16 managed via Prisma ORM (Identity, Focus, Habits, Gamification, Projects, Notifications).
- **Queue / Background Worker**: Standalone Node process powered by `pg-boss` for email delivery (Postmark), calendar projections, push notifications, and daily score settlement.
- **Hosting**: AWS EC2 (`t4g.small`), RDS PostgreSQL (`db.t4g.micro`), S3 (Private media & public catalog), CloudFront CDN, and Caddy reverse proxy with automatic ACME TLS.

---

## 4. API Envelope & Conventions

All endpoints adhere to a standardized envelope:

**Success Response**:
```json
{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
```

**Error Response**:
```json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested task was not found.",
    "requestId": "req_abc123"
  }
}
```

---

## 5. Summary & Index

- Home: https://app.focusbetter.io
- Login: https://app.focusbetter.io/login
- Signup: https://app.focusbetter.io/signup
- Privacy Policy: https://app.focusbetter.io/privacy
- Terms of Service: https://app.focusbetter.io/terms
- Public Basecamp Share: https://app.focusbetter.io/share/[slug]
- Short LLM Summary: https://app.focusbetter.io/llms.txt