CASAN/docs/technical_architecture.md

# Technical Architecture — OKR Web Application

**Version:** 1.0.0  
**Purpose:** Defines the system technical architecture optimized for Docker-based local development.  
**Target Team Size:** 3–5 developers  
**Environment:** Localhost-first, internal system, not public internet

---

## I. Technology Stack

### 1. Frontend

| Technology | Version | Role |
|------------|---------|------|
| React | 18.x | UI framework |
| Vite | 5.x | Build tool & dev server with HMR |
| React Router DOM | 6.x | Client-side routing |
| TanStack Query (React Query) | 5.x | Server state management, caching |
| Axios | 1.x | HTTP client with interceptors |
| React Hook Form | 7.x | Form state and submission |
| Zod | 3.x | Schema validation (shared with backend types) |
| Tailwind CSS | 3.x | Utility-first styling |

**Decisions:**

- **Vite** over Create React App: significantly faster HMR in Docker dev mode via volume mounts.
- **TanStack Query** for server state: eliminates manual loading/error state boilerplate for API calls.
- **React Router DOM v6** is sufficient for this internal SPA — no SSR needed.
- **Error boundary:** A single `<AppErrorBoundary>` wraps the router root. API errors are caught at the TanStack Query layer with a global `onError` handler; only component crashes bubble to the boundary.
- **Form validation:** Zod schemas defined in a shared `src/schemas/` directory; used by React Hook Form's `zodResolver` on the frontend and replicated for backend DTOs, ensuring consistent validation rules.

---

### 2. Backend

| Technology | Version | Role |
|------------|---------|------|
| Node.js | 20 LTS | Runtime |
| NestJS | 10.x | Application framework |
| Prisma | 5.x | ORM, schema management, migrations |
| @nestjs/jwt | latest | JWT sign/verify (no Passport — Username/Password only, no SSO) |
| bcrypt | 5.x | Password hashing |
| class-validator + class-transformer | latest | DTO validation |
| @nestjs/swagger | 7.x | OpenAPI / Swagger UI |
| dotenv / @nestjs/config | — | ~~Not used~~ — values hardcoded (workshop) |

**Decisions:**

- **NestJS over Express:** For a 3–5 person team, NestJS's module/controller/service structure enforces consistent code organisation without custom conventions. Decorators (`@Get`, `@UseGuards`, `@Body`) reduce boilerplate.
- **Prisma over TypeORM:** Prisma's `schema.prisma` is a single source of truth for DB schema, migrations, and type generation. The generated client provides full type-safety. TypeORM entities and migrations drift more easily.
- **JWT only (no session store):** Stateless authentication is appropriate for an internal tool. Access token TTL = 1h, refresh token TTL = 7d, stored in HttpOnly cookies.
- **No env files (workshop):** All configuration values (DB credentials, JWT secret, ports) are hardcoded directly in `docker-compose.yml` and application config. No `.env` file or `@nestjs/config` needed.
- **Swagger:** Auto-generated from NestJS decorators; available at `/api/docs` in dev environment only.

---

### 3. Database

| Technology | Version | Role |
|------------|---------|------|
| MySQL | 8.0 | Primary relational database |
| Prisma Migrate | 5.x | Schema migration engine |
| Prisma Studio | 5.x | GUI for DB inspection (dev only) |

**Decisions:**

- **MySQL 8.x:** Required by constraint. Uses `mysql2` driver via Prisma.
- **Migration strategy:** `prisma migrate dev` generates versioned SQL migration files under `prisma/migrations/`. Applied automatically on container start via entrypoint script.
- **Index strategy:** Primary keys on all tables. Composite index on `(objective_id, deadline)` for Key Result queries. Index on `user.email` for login lookups.
- **Authentication plugin:** MySQL is started with `--default-authentication-plugin=mysql_native_password` for compatibility with the `mysql2` driver.
- **Connection pooling:** Prisma's built-in connection pool, configured via `DATABASE_URL` parameter `connection_limit=10`. Sufficient for local dev and small team.
- **Volume persistence:** Named Docker volume `mysql_data` persists across `docker-compose up/down`. Destroyed only by `docker-compose down -v` (explicit reset).
- **Dev vs production:** Single `schema.prisma` file. All environment-specific values are set directly in `docker-compose.yml`. No separate `.env` files.

---

## II. Repository Structure (Monorepo)

```
okr-web/
├── backend/                    # NestJS API service
│   ├── src/
│   │   ├── main.ts             # Bootstrap, Swagger, global pipes
│   │   ├── app.module.ts       # Root module
│   │   ├── auth/               # JWT auth module
│   │   ├── users/              # User CRUD module
│   │   ├── objectives/         # Objective module
│   │   ├── key-results/        # Key Result module
│   │   └── common/             # Guards, filters, interceptors, decorators
│   ├── prisma/
│   │   ├── schema.prisma       # DB schema (single source of truth)
│   │   ├── migrations/         # Auto-generated migration SQL files
│   │   └── seed.ts             # Mock data seeding script
│   ├── test/                   # Jest integration tests
│   ├── .env.example            # (not used — values hardcoded for workshop)
│   ├── Dockerfile
│   └── package.json
│
├── frontend/                   # React + Vite SPA
│   ├── src/
│   │   ├── main.tsx            # React root
│   │   ├── App.tsx             # Router setup + error boundary
│   │   ├── pages/              # Route-level components
│   │   │   ├── Login.tsx
│   │   │   ├── Dashboard.tsx
│   │   │   ├── OKRDetail.tsx
│   │   │   ├── CreateObjective.tsx
│   │   │   └── KeyResultDetail.tsx
│   │   ├── components/
│   │   │   ├── layout/         # Sidebar, Header, AppLayout
│   │   │   └── ui/             # Button, Table, ProgressBar, Badge
│   │   ├── hooks/              # useAuth, useObjectives, useKeyResults
│   │   ├── lib/
│   │   │   ├── api.ts          # Axios instance, interceptors
│   │   │   └── queryClient.ts  # TanStack Query client config
│   │   ├── schemas/            # Zod validation schemas
│   │   └── types/              # TypeScript interfaces
│   ├── public/
│   ├── index.html
│   ├── vite.config.ts
│   ├── tailwind.config.ts
│   ├── Dockerfile
│   └── package.json
│
├── database/
│   └── init/                   # (Unused at runtime; Prisma handles migration)
│
├── docker/
│   └── wait-for-db.sh          # Shell script: polls MySQL until ready
│
├── docs/                       # Architecture, SRS, BD, DD documents
│
├── docker-compose.yml          # Full stack orchestration (values hardcoded)
├── docker-compose.test.yml     # E2E test override (Playwright)
└── README.md
```

---

## III. Docker Compose Architecture (MANDATORY)

### Full `docker-compose.yml`

```yaml
services:
  mysql:
    image: mysql:8.0
    container_name: okr_mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: okr_db
      MYSQL_USER: okr_user
      MYSQL_PASSWORD: okr_password
    command: --default-authentication-plugin=mysql_native_password
    ports:
      - '3307:3306'
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - okr_network
    healthcheck:
      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-u', 'root', '-prootpassword']
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: okr_backend
    restart: unless-stopped
    environment:
      DATABASE_URL: mysql://okr_user:okr_password@mysql:3306/okr_db
      JWT_SECRET: workshop_jwt_secret_key
      JWT_REFRESH_SECRET: workshop_jwt_refresh_secret_key
      PORT: 3000
    ports:
      - '3000:3000'
    depends_on:
      mysql:
        condition: service_healthy
    networks:
      - okr_network
    command: >
      sh -c "
        npx prisma migrate deploy &&
        npx prisma db seed &&
        npm run start:dev
      "

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: okr_frontend
    restart: unless-stopped
    environment:
      VITE_API_URL: http://localhost:3000
    ports:
      - '5173:5173'
    depends_on:
      - backend
    networks:
      - okr_network

  adminer:
    image: adminer:4
    container_name: okr_adminer
    restart: unless-stopped
    ports:
      - '8080:8080'
    depends_on:
      - mysql
    networks:
      - okr_network

volumes:
  mysql_data:
    driver: local

networks:
  okr_network:
    driver: bridge
```

### Container Startup Sequence

```
1. mysql starts → healthcheck polls mysqladmin ping
   - Uses mysql_native_password authentication plugin
   - Host port 3307 mapped to container port 3306
2. backend waits (depends_on: mysql condition: service_healthy)
3. backend command runs sequentially:
   a. npx prisma migrate deploy  → applies pending SQL migrations
   b. npx prisma db seed          → seeds mock data (idempotent)
   c. npm run start:dev           → starts NestJS with --watch
4. frontend starts → Vite dev server with HMR
   - API proxy configured via VITE_API_URL pointing to http://localhost:3000
5. adminer available at http://localhost:8080
```

### `docker/wait-for-db.sh`

> Not required when using `depends_on: condition: service_healthy`. Kept as a fallback utility:

```sh
#!/bin/sh
set -e

HOST=$1
PORT=$2
shift 2

until mysqladmin ping -h "$HOST" -P "$PORT" --silent; do
  echo "Waiting for MySQL at $HOST:$PORT..."
  sleep 2
done

exec "$@"
```

---

## IV. Mock Data Seeding Strategy

### Why Seeding is Required

- Developers need realistic OKR data on first container start (no manual data entry).
- E2E tests (Playwright) require a deterministic database state — random data breaks assertions.
- Onboarding new developers: `docker-compose up --build` produces a fully working system in one command.

### Seed Execution Rules

| Environment | Seed Runs? | Controlled By |
|-------------|------------|---------------|
| development | Always     | Hardcoded in entrypoint command |
| test        | Yes (reset before each E2E run) | `docker-compose.test.yml` override |

### Idempotency Pattern

The seed script uses `upsert` (Prisma's `createOrUpdate`) keyed on stable identifiers (email for users, slug for objectives). Running the seed twice produces no duplicates:

```typescript
// backend/prisma/seed.ts
import { PrismaClient } from '@prisma/client';
import * as bcrypt from 'bcrypt';

const prisma = new PrismaClient();

async function main() {
  // Always seed — workshop environment, no env gate needed

  // --- Users ---
  const passwordHash = await bcrypt.hash('Password@123', 10);

  const admin = await prisma.user.upsert({
    where: { email: 'admin@okr.local' },
    update: {},
    create: { name: 'System Admin', email: 'admin@okr.local', password: passwordHash, role: 'ADMIN' },
  });

  const manager = await prisma.user.upsert({
    where: { email: 'manager@okr.local' },
    update: {},
    create: { name: 'Nguyen Van Manager', email: 'manager@okr.local', password: passwordHash, role: 'MANAGER' },
  });

  const employee = await prisma.user.upsert({
    where: { email: 'employee@okr.local' },
    update: {},
    create: { name: 'Nguyen Van A', email: 'employee@okr.local', password: passwordHash, role: 'EMPLOYEE' },
  });

  // --- Objectives ---
  const obj1 = await prisma.objective.upsert({
    where: { id: 1 },
    update: {},
    create: {
      title: 'POC AI for SQL Injection prevention',
      description: 'Evaluate AI tools for automated SQL injection detection',
      ownerId: employee.id,
      quarter: 'Q2/2026',
      status: 'IN_PROGRESS',
    },
  });

  const obj2 = await prisma.objective.upsert({
    where: { id: 2 },
    update: {},
    create: {
      title: 'AI for All: Upskill department members',
      description: 'Ensure all department members have practical AI skills',
      ownerId: manager.id,
      quarter: 'Q2/2026',
      status: 'NOT_STARTED',
    },
  });

  // --- Key Results ---
  await prisma.keyResult.upsert({
    where: { id: 1 },
    update: {},
    create: {
      objectiveId: obj1.id,
      title: 'Complete 3 POC sessions with security team',
      progress: 0,
      startValue: 0,
      targetValue: 3,
      deadline: new Date('2026-06-30'),
    },
  });

  await prisma.keyResult.upsert({
    where: { id: 2 },
    update: {},
    create: {
      objectiveId: obj2.id,
      title: 'AI for All members in department (100 people)',
      progress: 0,
      startValue: 0,
      targetValue: 100,
      deadline: new Date('2026-06-30'),
    },
  });

  console.log('Seed completed successfully.');
}

main()
  .catch((e) => { console.error(e); process.exit(1); })
  .finally(() => prisma.$disconnect());
```

### Seed Categories

| Category | Description | Sample Records |
|----------|-------------|----------------|
| Users | Admin, Manager, Employee accounts with hashed passwords | 3 users |
| Objectives | Sample OKRs per quarter | 2 objectives |
| Key Results | KRs linked to objectives with progress | 4 KRs |

### Database Reset

```bash
# Full reset: destroys volume (all data), rebuilds from scratch
docker-compose down -v && docker-compose up --build

# Soft reset: re-run seed only (keeps schema, replaces data)
docker-compose exec backend npx prisma db seed
```

### E2E Test Seed Isolation

`docker-compose.test.yml` overrides the backend command to always run seed before Playwright tests:

```yaml
# docker-compose.test.yml
services:
  backend:
    environment:
      SEED_ON_START: 'true'
    command: >
      sh -c "
        npx prisma migrate reset --force &&
        npx prisma db seed &&
        npm run start:prod
      "
```

---

## V. Local Development Flow

### First-Time Setup

```bash
git clone <repo-url>
cd okr-web
docker-compose up --build     # Builds all images, migrates DB, seeds, starts all services
```

After ~60 seconds:

| Service | URL |
|---------|-----|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:3000/api/v1 |
| Swagger UI | http://localhost:3000/api/docs |
| Adminer (DB GUI) | http://localhost:8080 |

Default login credentials (seeded):

| Role | Email | Password |
|------|-------|----------|
| Admin | admin@okr.local | Password@123 |
| Manager | manager@okr.local | Password@123 |
| Employee | employee@okr.local | Password@123 |

### Hot Reload

- **Backend:** Source code is baked into the Docker image. Changes require `docker compose up --build backend` to rebuild.
- **Frontend:** Source code is baked into the Docker image. Changes require `docker compose up --build frontend` to rebuild.

### Configuration

- All values (DB credentials, JWT secrets, ports) are hardcoded in `docker-compose.yml` — no `.env` file required. This is intentional for the workshop environment.
- Frontend uses Vite's proxy (`vite.config.ts`): requests to `/api` are proxied to the backend service. The proxy target is configured via `VITE_API_URL` environment variable.

### Daily Developer Workflow

```bash
# Start everything
docker-compose up

# View logs for one service
docker-compose logs -f backend

# Open shell in container
docker-compose exec backend sh

# Reset DB and reseed
docker-compose down -v && docker-compose up

# Run specific migration
docker-compose exec backend npx prisma migrate dev --name add_comments_table
```

---

## VI. API Design Principles

### Conventions

- Base path: `/api/v1`
- Resource naming: plural nouns (`/objectives`, `/key-results`, `/users`)
- HTTP verbs: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial update), `DELETE`
- Auth: `Authorization: Bearer <token>` header on all protected routes

### Standard Response Envelope

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}
```

### Error Response Structure

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title must not be empty",
    "details": [
      { "field": "title", "message": "title must not be empty" }
    ]
  }
}
```

### Pagination (Query Params)

```
GET /api/v1/objectives?page=1&limit=20&quarter=Q2%2F2026&ownerId=3
```

### Key Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/v1/auth/login | Login, returns access + refresh tokens |
| POST | /api/v1/auth/refresh | Refresh access token |
| GET | /api/v1/objectives | List objectives (filterable) |
| POST | /api/v1/objectives | Create objective |
| GET | /api/v1/objectives/:id | Get objective with KRs |
| PUT | /api/v1/objectives/:id | Update objective |
| POST | /api/v1/objectives/:id/key-results | Create KR under objective |
| PATCH | /api/v1/key-results/:id/progress | Update KR progress |
| GET | /api/v1/users | List users (Admin/Manager only) |

---

## VII. Authentication & Security

### JWT Flow

```
Login → POST /auth/login
  ↓
Backend validates credentials (bcrypt.compare)
  ↓
Issues accessToken (1h TTL) + refreshToken (7d TTL)
  ↓
Both stored as HttpOnly, SameSite=Strict cookies (not localStorage)
  ↓
Each request: JwtAuthGuard extracts token from cookie, validates signature
  ↓
On 401: Frontend calls POST /auth/refresh → new accessToken issued
```

### Security Measures

| Concern | Implementation |
|---------|---------------|
| Password hashing | bcrypt, cost factor 12 |
| SQL injection | Prisma parameterised queries (no raw SQL in application code) |
| JWT secret | Hardcoded in `docker-compose.yml` (workshop only — never do this in production) |
| CORS | `@nestjs/common` CORS configured to `http://localhost:5173` only |
| Role enforcement | `@Roles` decorator + `RolesGuard` on controller methods |
| Input validation | `class-validator` + `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })` |
| Rate limiting | `@nestjs/throttler`, 60 req/min per IP on auth endpoints |
| Sensitive data | Passwords never returned in API responses (`@Exclude()` on password field) |

### Role-Based Access Control

| Role | Permissions |
|------|-------------|
| ADMIN | Full access to all resources and user management |
| MANAGER | View all objectives, approve/reject, view team members |
| EMPLOYEE | Create/edit own objectives, update own KR progress |

---

## VIII. Logging & Error Handling

### Backend Logging (Pino via nestjs-pino)

- All logs output as structured JSON (useful for future ELK/Loki integration)
- Request logging middleware logs: `method`, `url`, `statusCode`, `responseTimeMs`, `userId`
- Log levels: `error`, `warn`, `info`, `debug` (debug disabled in production)

```json
{
  "level": "info",
  "time": "2026-04-05T10:23:11.000Z",
  "reqId": "req-abc123",
  "method": "PATCH",
  "url": "/api/v1/key-results/3/progress",
  "statusCode": 200,
  "responseTimeMs": 34,
  "userId": 5
}
```

### Centralised Error Filter (NestJS)

A global `HttpExceptionFilter` catches all exceptions and maps them to the standard error envelope. Unhandled errors return HTTP 500 with `INTERNAL_SERVER_ERROR` code — stack traces logged server-side, never exposed to client.

### Frontend Error Boundary

```tsx
// src/App.tsx
<AppErrorBoundary fallback={<ErrorPage />}>
  <RouterProvider router={router} />
</AppErrorBoundary>
```

TanStack Query's `onError` global callback handles API error toasts without crashing the component tree.

---

## IX. Testing Strategy

### Backend (Jest)

- **Unit tests:** Services tested in isolation with Prisma mocked via `jest.mock`.
- **Integration tests:** `@nestjs/testing` spins up full NestJS app with SQLite in-memory database override.
- Test files co-located under `backend/test/`.

### Frontend

- **Component tests:** Vitest + React Testing Library for unit-level component behaviour.
- **No Storybook** for this scope — too much overhead for a 3–5 person team.

### E2E (Playwright)

- Tests live in `e2e/` directory at the project root.
- Playwright connects to the running `docker-compose.test.yml` stack.
- Each test suite calls `resetDb()` helper (hits a dev-only `/api/v1/test/reset` endpoint) to restore seed state.
- Scenarios cover: login, create objective, update KR progress, dashboard display.

```bash
# Run E2E tests
docker-compose -f docker-compose.yml -f docker-compose.test.yml up -d
npx playwright test
```

### Coverage Targets

| Layer | Target |
|-------|--------|
| Backend service unit tests | ≥ 70% |
| Critical auth/KR flows | 100% integration coverage |
| E2E happy paths | All 5 screens covered |

---

## X. Scalability Considerations

While this is localhost-first, the architecture does not create dead-ends:

| Concern | Current Decision | Path to Scale |
|---------|-----------------|---------------|
| Database | Single MySQL container | Extract to managed RDS; Prisma `DATABASE_URL` is the only change |
| Auth | Stateless JWT | No server-side session store means horizontal scaling of backend is trivial |
| Frontend | SPA static build | `npm run build` output can be deployed to S3/CDN or served via Nginx |
| Config | Hardcoded in `docker-compose.yml` | Move to `.env` + `@nestjs/config`, then AWS Parameter Store / Vault |
| Migrations | `prisma migrate deploy` | Identical command in CI/CD pipeline — no code change needed |
| CI/CD | Not configured | GitHub Actions: `docker-compose -f docker-compose.test.yml up`, run tests, push image |

---

## XI. Architecture Rationale

### NestJS over plain Express

For 3–5 developers, NestJS enforces a module/controller/service structure that prevents the "spaghetti Express router" problem. The decorators and DI system make the codebase navigable without tribal knowledge. The trade-off is a slightly steeper learning curve (decorators, DI concepts), which is acceptable for a workshop project that may grow.

### Prisma over TypeORM

Prisma's `schema.prisma` is the single source of truth for the database schema. Migrations are generated automatically and are plain SQL files — reviewable in PRs. TypeORM requires manual synchronisation between entity decorators and migration files, which causes drift in team environments. Prisma's type-safe client also eliminates an entire class of runtime query errors.

### MySQL 8.x

Required by the constraint. MySQL 8 features (`ROW_NUMBER`, recursive CTEs, window functions) may be useful for reporting queries later. The `utf8mb4` charset handles Unicode (Vietnamese characters in objective titles).

### Docker Compose

All-in-one orchestration that requires zero local installation beyond Docker. A new developer runs one command and has a working system. No "works on my machine" issues because the MySQL version, Node version, and OS dependencies are pinned in Dockerfiles.

### Mock Seeding in Lifecycle

Seeding is not an afterthought but part of the container startup sequence. This decision means:
1. The system is always in a demonstrable state for stakeholders.
2. E2E tests are deterministic.
3. New developers are productive within minutes, not hours.

The idempotent upsert pattern means accidental double-seeds cause no harm.

### Trade-offs Accepted

| Decision | Trade-off |
|----------|-----------|
| HttpOnly cookies for JWT | Requires CORS configuration; slightly more complex than localStorage, but significantly more secure |
| Single monorepo | Simpler for a small team; would need Nx/Turborepo tooling if the codebase grows beyond ~10 modules |
| No Redis (no session/queue) | Refresh token revocation requires DB check; acceptable for internal tool, not acceptable for high-security systems |
| No message queue | Progress update events are synchronous; sufficient for 3–5 developers testing locally |