# h-hamdy/focustracker architecture

> Architecture diagram of the GitHub repository h-hamdy/focustracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h-hamdy/focustracker
- Repository: https://github.com/h-hamdy/focustracker

## Overview

##### Project type and purpose
- FocusTrack is a full-stack web application for Pomodoro-style time tracking, analytics, and user ranking.
- Frontend is built with Next.js; backend is built with NestJS and Prisma ORM; data is stored in PostgreSQL.

##### File structure
- Top-level directories:
– frontend/ – Next.js app, UI pages under app/auth and app, global CSS, Tailwind config
– backend/ – NestJS modules (auth, prisma, core app), Prisma schema and migrations, test suites, lint/build configs
- Patterns & configurations:
– NestJS modules map to domain areas: auth, prisma
– Prisma directory holds schema.prisma and migrations → database layer
– Swagger decorators likely in controllers for API docs
– Railway deployment descriptors are implied (no Dockerfile present)

##### README for additional insights
- Key features: JWT auth, Pomodoro timer (real-time & manual tracking), analytics charts, weekly leaderboard
- AES-256 encryption for sensitive data at rest
- Swagger for API documentation
- Deployment on Railway for frontend, backend, database

a. Main components
1. Client / Browser (Next.js UI)
2. Frontend server (Next.js on Vercel/Railway)
3. Backend API (NestJS REST controllers)
4. Database (PostgreSQL with Prisma)
5. External/Infrastructure services: Railway, Swagger UI, JWT issuer, AES-256 encryption module
b. Relationships & interactions
- User ↔ Next.js UI: HTTP(S) for rendering pages & fetching data via client-side calls
- Next.js UI ↔ NestJS API: REST calls (Axios/fetch) with Bearer JWT in headers
- NestJS API ↔ PostgreSQL: Prisma client executes SQL for CRUD, migrations apply schema changes
- Auth service issues and verifies JWT; encryption service handles AES-256 when persisting sensitive fields
- Swagger UI exposes /api-docs endpoint for interactive API exploration
c. Architectural patterns & design principles
- Modular monolith on the backend: NestJS modules per domain (auth, prisma, app)
- MVC-style on backend: Controllers → Services → ORM (Prisma)
- Component-based UI in Next.js (app/ directory + shared ui components)
- Secure layering: transport (HTTPS), JWT at API layer, encryption at data layer
d. Key technologies & libraries
- Frontend: Next.js routing/app directory, Tailwind CSS, ESLint, utility functions in lib/utils.ts
- Backend: NestJS, TypeScript, Prisma ORM, JWT (@nestjs/jwt), AES-256 encryption library, Jest for tests
- Database: PostgreSQL (migrations in prisma/migrations)
- DevOps: Railway for hosting, Swagger (via @nestjs/swagger)

##### Elements
– UI → API (with “REST/HTTPS + JWT”)
– API → Database (with “Prisma ORM/SQL”)
– API ↔ Encryption service (“AES-256”)
– Blue for UI components
– Green for backend modules
– Orange for data persistence layer
– Purple for external services
– Rounded rectangles for services/modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        NextJSClient["Next.js Client"]:::ui
        LoginPage["Login Page"]:::ui
        SignupPage["Signup Page"]:::ui
        DashboardPage["Dashboard Page"]:::ui
        GlobalsCSS["globals.css"]:::ui
        TailwindConfig["tailwind.config.ts"]:::ui
        UIButton["button.tsx (UI Component)"]:::ui
        Utils["utils.ts (Utility Functions)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Main["main.ts (Bootstrap & Swagger)"]:::backend
        CoreModule["app.module.ts (Core App Module)"]:::backend
        AppController["app.controller.ts"]:::backend
        AppService["app.service.ts"]:::backend
        AuthModule["auth.module.ts"]:::backend
        AuthController["auth.controller.ts"]:::backend
        AuthService["auth.service.ts"]:::backend
        PrismaModule["prisma.module.ts"]:::backend
        PrismaService["prisma.service.ts"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Schema["schema.prisma"]:::data
        Migrations["migrations (20250205155729_init)"]:::data
        DB[(PostgreSQL)]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Railway["Railway Deployment"]:::external
        SwaggerUI["Swagger UI"]:::external
        JWTService["JWT Issuer/Verifier"]:::external
        EncryptionService["AES-256 Encryption"]:::external
    end

    %% Relationships
    User["User"]:::external -->|"interacts via HTTPS"| NextJSClient
    NextJSClient -->|"navigates to"| LoginPage
    NextJSClient -->|"navigates to"| SignupPage
    NextJSClient -->|"navigates to"| DashboardPage
    NextJSClient -->|"imports styles"| GlobalsCSS
    NextJSClient -->|"imports config"| TailwindConfig
    NextJSClient -->|"uses component"| UIButton
    NextJSClient -->|"uses utils"| Utils
    NextJSClient -->|"REST/HTTPS + JWT"| Main

    Railway --> Main
    Main -->|"/api-docs"| SwaggerUI

    Main --> CoreModule
    CoreModule --> AppController
    AppController --> AppService

    CoreModule --> AuthModule
    AuthModule --> AuthController
    AuthController --> AuthService

    CoreModule --> PrismaModule
    PrismaModule --> PrismaService
    PrismaService -->|"Prisma ORM/SQL"| DB

    AuthService -->|"issues/verifies"| JWTService
    AuthService -->|"encrypts/decrypts"| EncryptionService

    %% Click Events
    click NextJSClient "https://github.com/h-hamdy/focustracker/tree/main/frontend/app"
    click LoginPage "https://github.com/h-hamdy/focustracker/blob/main/frontend/app/auth/login/page.tsx"
    click SignupPage "https://github.com/h-hamdy/focustracker/blob/main/frontend/app/auth/signup/page.tsx"
    click DashboardPage "https://github.com/h-hamdy/focustracker/blob/main/frontend/app/auth/Dashboard/page.tsx"
    click GlobalsCSS "https://github.com/h-hamdy/focustracker/blob/main/frontend/app/globals.css"
    click TailwindConfig "https://github.com/h-hamdy/focustracker/blob/main/frontend/tailwind.config.ts"
    click UIButton "https://github.com/h-hamdy/focustracker/blob/main/frontend/components/ui/button.tsx"
    click Utils "https://github.com/h-hamdy/focustracker/blob/main/frontend/lib/utils.ts"
    click Main "https://github.com/h-hamdy/focustracker/blob/main/backend/src/main.ts"
    click CoreModule "https://github.com/h-hamdy/focustracker/blob/main/backend/src/app.module.ts"
    click AppController "https://github.com/h-hamdy/focustracker/blob/main/backend/src/app.controller.ts"
    click AppService "https://github.com/h-hamdy/focustracker/blob/main/backend/src/app.service.ts"
    click AuthModule "https://github.com/h-hamdy/focustracker/blob/main/backend/src/auth/auth.module.ts"
    click AuthController "https://github.com/h-hamdy/focustracker/blob/main/backend/src/auth/auth.controller.ts"
    click AuthService "https://github.com/h-hamdy/focustracker/blob/main/backend/src/auth/auth.service.ts"
    click PrismaModule "https://github.com/h-hamdy/focustracker/blob/main/backend/src/prisma/prisma.module.ts"
    click PrismaService "https://github.com/h-hamdy/focustracker/blob/main/backend/src/prisma/prisma.service.ts"
    click Schema "https://github.com/h-hamdy/focustracker/blob/main/backend/prisma/schema.prisma"
    click Migrations "https://github.com/h-hamdy/focustracker/tree/main/backend/prisma/migrations/20250205155729_init"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef backend fill:#D6F5D6,stroke:#009900,color:#000
    classDef data fill:#FFE5B4,stroke:#FF9900,color:#000
    classDef external fill:#E5D6FF,stroke:#9900CC,color:#000
```
