# TaskFlow Architecture

## System Overview

TaskFlow is a task management API service built with a layered architecture pattern.

```mermaid
graph TB
    Client[Client Applications] --> LB[Load Balancer / Nginx]
    LB --> API[Express API Server]
    API --> MW[Middleware Stack]
    MW --> Auth[Auth Middleware]
    MW --> Validator[Validator Middleware]
    MW --> Logger[Request Logger]
    Auth --> Controllers[Controllers]
    Validator --> Controllers
    Controllers --> Services[Service Layer]
    Services --> TypeORM[TypeORM]
    TypeORM --> PG[(PostgreSQL)]
    Services --> Cache[Redis Cache]
    Cache --> Redis[(Redis)]
```

## Architecture Layers

### 1. Presentation Layer (Controllers)

Handles HTTP request/response mapping. Controllers are thin and delegate to services.

- `task-controller.ts` - Task CRUD + comments
- `user-controller.ts` - Registration, login, profile
- `project-controller.ts` - Project management

### 2. Business Logic Layer (Services)

Contains domain logic, validation, and orchestration.

- `task-service.ts` - Task operations with caching
- `user-service.ts` - Auth, registration, password hashing
- `project-service.ts` - Project CRUD

### 3. Data Access Layer (TypeORM)

Entity-based ORM with PostgreSQL.

- Entities: `Task`, `User`, `Project`, `Comment`, `TaskTag`
- Automatic migrations in development
- Connection pooling (configurable per environment)

### 4. Infrastructure Layer

- **Database**: PostgreSQL 15 with connection pooling
- **Cache**: Redis 7 for read-through caching (5 min TTL)
- **Auth**: JWT with Bearer token scheme
- **Logging**: Winston with console + file transports

## Data Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant A as Auth Middleware
    participant V as Validator
    participant Ctrl as Controller
    participant Svc as Service
    participant DB as PostgreSQL
    participant R as Redis

    C->>A: HTTP Request + Bearer Token
    A->>A: Verify JWT
    A->>V: Forward request
    V->>V: Validate with Joi
    V->>Ctrl: Validated request
    Ctrl->>Svc: Call service method
    Svc->>R: Check cache
    alt Cache Hit
        R-->>Svc: Cached data
    else Cache Miss
        Svc->>DB: Query data
        DB-->>Svc: Result
        Svc->>R: Update cache
    end
    Svc-->>Ctrl: Response data
    Ctrl-->>C: HTTP Response
```

## Key Design Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| ORM | TypeORM | TypeScript-native, decorator-based, active community |
| Cache Strategy | Read-through | Simple to implement, good for read-heavy task queries |
| Auth | JWT stateless | Horizontally scalable, no session store needed |
| Validation | Joi + middleware | Declarative schemas, reusable, early rejection |
| Logging | Winston | Structured JSON logs, multiple transports |

## Scalability

- Horizontal: Stateless API servers behind load balancer
- Database: Read replicas for reporting queries
- Cache: Redis cluster for high availability
- Rate limiting: Planned for API gateway layer