Focus Tracking Application

A production-grade Focus Tracking application designed to help users manage their time effectively using the Pomodoro technique, detailed reporting, and persistent session tracking. Built with modern web technologies including Next.js 16, Express, Prisma, and Clerk Authentication.

🏗 System Architecture

The application follows a client-server architecture. The frontend (Next.js) handles user interaction and real-time state, while the backend (Express) manages data persistence, authentication verification, and business logic.

graph TD
    subgraph Client ["Client (Next.js 16)"]
        UI[User Interface]
        AuthClient[Clerk Client SDK]
        Query[TanStack Query]
        Worker[Web Worker Timer]
    end

    subgraph Server ["Server (Express + Node.js)"]
        API[API Gateway]
        AuthMiddleware[Clerk Auth Middleware]
        SessionService[Session Service]
        UserService[User Service]
    end

    subgraph Infrastructure
        DB[(PostgreSQL)]
        Redis[(Upstash Redis)]
        ClerkService[Clerk Auth Service]
    end

    UI -->|Interacts| AuthClient
    UI -->|Fetches Data| Query
    UI -->|Timer Logic| Worker
    
    Query -->|HTTP Requests| API
    Worker -->|Sync Heartbeats| API
    
    API --> AuthMiddleware
    AuthMiddleware -->|Verifies Token| ClerkService
    
    API --> SessionService
    API --> UserService
    
    SessionService -->|Persists| DB
    UserService -->|Persists| DB
    SessionService -.->|Cache/Rate Limit| Redis

Loading

🚀 Key Features

• Real-time Focus Timer: robust timer implementation using Web Workers to prevent drift even when the tab is inactive.
• Secure Authentication: Integrated with Clerk for seamless and secure user sign-up/sign-in flows.
• Session Tracking: Detailed tracking of focus sessions (Active, Completed, Abandoned) with duration metrics.
• Data Persistence: PostgreSQL database via Prisma ORM for reliable data storage.
• Responsive Design: Modern, responsive UI built with Tailwind CSS and Radix UI primitives.
• Heartbeat Mechanism: Ensures accurate session tracking even if the browser crashes or disconnects.

🛠 Tech Stack

Client (/client)

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS, Framer Motion, Lucide Icons
• State & Data: TanStack Query (React Query)
• UI Components: Radix UI (Headless), Class Variance Authority (CVA)
• Auth: @clerk/nextjs
• Utilities: date-fns, clsx, tailwind-merge

Server (/server)

• Runtime: Node.js
• Framework: Express.js
• Language: TypeScript
• Database: PostgreSQL
• ORM: Prisma
• Caching/KV: Upstash Redis
• Auth: @clerk/clerk-sdk-node
• Security: Helmet, CORS
• Validation: Zod

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v20+ recommended)
• npm or yarn
• PostgreSQL Database (Local or Cloud like Neon/Supabase)
• Redis instance (Optional, for caching features)
• Clerk Account (for Authentication keys)

📦 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd <project-folder>

2. Server Setup

Navigate to the server directory and install dependencies:

cd server
npm install

Create a .env file in the server root:

# Server Configuration
PORT=5000
DATABASE_URL="postgresql://user:password@localhost:5432/focus_db?schema=public"
ALLOWED_ORIGINS="http://localhost:3000"

# Clerk Authentication
CLERK_SECRET_KEY=sk_test_...
CLERK_PUBLISHABLE_KEY=pk_test_...

Initialize the Database:

# Generate Prisma Client
npx prisma generate

# Push schema to database
npx prisma db push

Start the Server:

# Development Mode
npm run dev

3. Client Setup

Open a new terminal, navigate to the client directory and install dependencies:

cd client
npm install

Create a .env.local file in the client root:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:5000

Start the Client:

# Development Mode
npm run dev

📂 Project Structure

├── client/                 # Next.js Frontend Application
│   ├── src/
│   │   ├── app/           # App Router Pages & Layouts
│   │   ├── components/    # Reusable UI Components
│   │   ├── hooks/         # Custom React Hooks
│   │   ├── lib/           # Utility functions & API clients
│   │   └── styles/        # Global styles
│   ├── public/            # Static assets
│   └── ...config files    # Next.js, Tailwind, TS Config
│
├── server/                 # Express Backend Application
│   ├── src/
│   │   ├── api/           # Route Handlers (Controllers)
│   │   ├── infra/         # DB & External Services
│   │   │   └── db/        # Prisma Schema & Client
│   │   ├── core/          # Business Logic & Types
│   │   └── index.ts       # Entry point
│   └── ...config files    # TS Config, Nodemon
│
└── README.md              # Project Documentation

🤝 Contributing

1. Fork the repository.
2. Create a new branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

---

Built for high-performance focus tracking.