# Construction Timelapse — Session Memory

## Tổng quan dự án
Hệ thống timelapse construction monitoring.
- **Repo**: `/Users/kingkong/Documents/code/timelaspe-2`
- **Stack**: Next.js + NestJS + PostgreSQL (Drizzle) + Python (device-agent) + Redis
- **Package manager**: Bun (KHÔNG dùng npm vì workspace protocol không hoạt động với nexus registry của môi trường)
- **Registry**: Luôn thêm `--registry https://registry.npmjs.org/` khi cài package từ public npm

---

## Kiến trúc hiện tại

```
construction-timelapse/
├── apps/
│   ├── api-server/          # NestJS — API backend
│   ├── web-dashboard/       # Next.js 14 — Dashboard UI
│   ├── worker/              # (stub)
│   └── device-agent/        # Python — Pi agent (chưa implement)
├── packages/
│   ├── shared-types/        # Shared TypeScript types/enums
│   └── config/             # tsconfig.base
└── docs/
    ├── api/                 # (trống)
    └── firmware/            # (trống)
```

---

## Workspace config (quan trọng!)
- **KHÔNG** dùng `apps/*` trong `workspaces` — `device-agent` là Python
- Workspace config đúng:
  ```json
  "workspaces": ["apps/api-server", "apps/web-dashboard", "apps/worker", "packages/*"]
  ```
- `@shared-types` **KHÔNG hợp lệ** — đổi thành `@shared/types` ở mọi nơi (package.json + tsconfig.json)
- Luôn `cd` vào workspace trước khi `bun add`

---

## Phase 1 — Trạng thái: ✅ HOÀN THÀNH

### Backend (apps/api-server)
**Chạy dev**: `cd apps/api-server && bun run dev`
**Build**: `cd apps/api-server && bun run build` ✅

**Auth module** (`src/modules/auth/`):
- `auth.module.ts`, `auth.controller.ts`, `auth.service.ts` — stub endpoints
- `strategies/jwt.strategy.ts`, `strategies/google.strategy.ts` — OAuth stubs

**Devices module** (`src/modules/devices/`):
- `devices.controller.ts` — 4 endpoints:
  - `POST /v1/devices/:deviceId/heartbeat` — X-API-Key auth
  - `GET /v1/devices` — list
  - `GET /v1/devices/:id` — detail
  - `GET /v1/devices/:id/heartbeats` — history
- `devices.service.ts` — heartbeat logic + API key verify
- `devices.repository.ts` — Drizzle queries
- `dto/heartbeat.dto.ts` — class-validator DTO

**Common guards/decorators** (`src/common/`):
- `guards/api-key.guard.ts` — X-API-Key header guard
- `decorators/api-key.decorator.ts` — `@ApiKey()` decorator

**Các module stub** (đều rỗng, chỉ để compile):
- `modules/orgs/`, `modules/projects/`, `modules/captures/`,
  `modules/videos/`, `modules/alerts/`, `realtime/`

### Dashboard (apps/web-dashboard)
**Chạy dev**: `cd apps/web-dashboard && bun run dev`
**Build**: `cd apps/web-dashboard && bun run build` ✅

- `pages/index.tsx` — Dashboard home (stats cards + recent devices)
- `pages/devices/index.tsx` — Device list
- `pages/devices/[id].tsx` — Device detail
- `components/StatsCard.tsx`, `DeviceCard.tsx`
- `hooks/useDashboardStats.ts`, `useDevices.ts`
- Tailwind CSS v3 + PostCSS đã setup

---

## Database (Drizzle Schema)
File: `apps/api-server/src/db/schema.ts`
- Enum: org_status, project_status, device_status, capture_status, video_status, alert_severity, alert_type, alert_state, user_role, command_result_status
- Tables: organizations, projects, users, memberships, sessions, magic_links, devices, device_heartbeats, captures, videos, video_jobs, commands, alert_rules, alerts, audit_logs, activity_logs
- Lưu ý: table names trong Drizzle schema là **lowercase** (`devices`, `deviceHeartbeats`) nhưng khi truy vấn phải dùng `devices`, `deviceHeartbeats` đúng tên export

---

## Các lỗi đã gặp và cách fix
1. `@shared-types` → đổi package name thành `@shared/types`
2. `device-agent` (Python) trong npm workspaces → loại khỏi workspaces
3. `npm install` không hoạt động → dùng `bun install --registry https://registry.npmjs.org/`
4. `bun add` với nexus registry → luôn thêm `--registry https://registry.npmjs.org/`
5. `db` không export được → import từ `database.module.ts` riêng
6. `experimentalDecorators` thiếu → thêm vào `packages/config/tsconfig.node.json`
7. `rootDir` conflict → bỏ `rootDir` khỏi tsconfig base

---

## TODO — Phase tiếp theo
1. **Phase 2**: Auth thực sự (JWT login, refresh token, Google OAuth)
2. **Phase 2**: Database migration + seed data (drizzle-kit push)
3. **Phase 2**: Projects/Orgs CRUD endpoints
4. **Phase 2**: Device-agent (Python) heartbeat sender
5. **Phase 2**: Realtime WebSocket (Socket.io) cho device status
6. **Phase 2**: Dashboard auth flow (login/logout)

---

## Lệnh dev nhanh
```bash
# Backend
cd apps/api-server && bun run dev  # http://localhost:3001

# Dashboard
cd apps/web-dashboard && bun run dev  # http://localhost:3000

# API test (heartbeat stub)
curl -X POST http://localhost:3001/v1/devices/test-device-1/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-key-123" \
  -d '{"deviceId":"test-device-1","apiKey":"dev-key-123","status":"online","storageFreeGb":50,"capturesToday":12,"firmwareVersion":"1.0.0"}'
```