190 lines
6.5 KiB
Markdown
190 lines
6.5 KiB
Markdown
# Design Document
|
|
|
|
## Architecture Overview
|
|
|
|
Layered architecture (UI → Service → Repository → Data) per `docs/architecture.md`. Next.js 15 App Router with Node.js Runtime only (no Edge Runtime). SQLite via better-sqlite3 accessed exclusively through a custom SQL wrapper. No Prisma.
|
|
|
|
```
|
|
app/ (UI: Route Handlers / Server Components / SSE)
|
|
↓
|
|
services/ (business logic, permission checks, transactions)
|
|
↓
|
|
repositories/ (SQL, parameter binding, logical-delete filter)
|
|
↓
|
|
lib/db/ (SQLite connection, SQL wrapper, Migration)
|
|
```
|
|
|
|
## Component Design
|
|
|
|
### 1. SQL Wrapper: `lib/db/sqlite.ts`
|
|
|
|
**Responsibilities**:
|
|
- SQLite connection management (singleton getDb(), WAL, foreign_keys ON)
|
|
- query<T> (multi-row), get<T> (single-row), execute (insert/update/delete), transaction<T>, close
|
|
- Error handling
|
|
|
|
**Implementation highlights**:
|
|
- dbPath = process.env.SQLITE_PATH ?? "./data/app.db"
|
|
- SqlParams = Record<string, unknown> | unknown[]
|
|
- All repositories use this wrapper; direct better-sqlite3 access forbidden
|
|
|
|
### 2. Migrator: `lib/db/migrator.ts`
|
|
|
|
**Responsibilities**:
|
|
- Create schema_migrations table
|
|
- Read .sql files from migrations dir in filename order
|
|
- Skip already-applied files (tracked in schema_migrations)
|
|
- Execute each file in a transaction; rollback on failure
|
|
|
|
### 3. Initial Schema: `lib/db/migrations/001_initial.sql`
|
|
|
|
16 tables: users, projects, project_members, board_threads, board_comments, chat_messages, todo_columns, todo_items, file_assets, project_notes, milestones, calendar_events, meetings, meeting_members, notifications, activity_logs + indexes.
|
|
|
|
### 4. Entity Types: `lib/types/`
|
|
|
|
PascalCase type files for each entity + union types (UserRole, UserStatus, ProjectStatus, ProjectMemberRole, etc.).
|
|
|
|
### 5. UserRepository
|
|
|
|
findById, findByEmail, create (with passwordHash), update (name/avatarUrl/role/status).
|
|
|
|
### 6. AuthService
|
|
|
|
register (hash password, create user), login (verify hash, issue session), logout, getCurrentUser, updateProfile. Uses bcrypt.
|
|
|
|
### 7. Session: `lib/auth/session.ts`, `lib/auth/getCurrentUser.ts`
|
|
|
|
Cookie-based session. getCurrentUser resolves the user from the request cookie.
|
|
|
|
### 8. ProjectRepository / ProjectMemberRepository
|
|
|
|
Project: findById, findByOwner, findByUser (via join), create, update, delete.
|
|
ProjectMember: findByProject, findByUser, add, remove, isMember, getRole.
|
|
|
|
### 9. ProjectService
|
|
|
|
createProject (owner becomes admin member), updateProject, addMember (permission check + notification hook later), removeMember, archiveProject, getDashboard skeleton.
|
|
|
|
## Data Flow
|
|
|
|
### Login
|
|
1. POST /api/auth/login → AuthService.login(email, password)
|
|
2. AuthService → UserRepository.findByEmail → verify bcrypt hash
|
|
3. Issue session cookie → return user
|
|
|
|
### Project creation
|
|
1. POST /api/projects → ProjectService.createProject(actorId, input)
|
|
2. ProjectService → permission (any authenticated user) → ProjectRepository.create
|
|
3. ProjectMemberRepository.add(projectId, ownerId, 'admin')
|
|
4. Return project
|
|
|
|
## Error Handling Strategy
|
|
|
|
### Custom Error Classes
|
|
- ValidationError (400) - field, value
|
|
- ForbiddenError (403)
|
|
- NotFoundError (404) - resource, id
|
|
- (409 for unique constraint - handled via SQLite error code)
|
|
|
|
### Error Handling Patterns
|
|
Route Handlers catch errors and map to HTTP status. Expected errors use custom classes; unexpected errors propagate + log.
|
|
|
|
## Test Strategy
|
|
|
|
### Unit Tests (Vitest)
|
|
- lib/db/sqlite.test.ts (query/get/execute/transaction, WAL, foreign keys)
|
|
- lib/db/migrator.test.ts (order, skip applied, rollback)
|
|
- repositories/UserRepository.test.ts
|
|
- services/AuthService.test.ts
|
|
- repositories/ProjectRepository.test.ts
|
|
- repositories/ProjectMemberRepository.test.ts
|
|
- services/ProjectService.test.ts
|
|
|
|
Tests use a temp SQLite file (in-memory or tmpdir) to avoid touching real data/.
|
|
|
|
### Integration Tests (Vitest)
|
|
- project-member-permission.test.ts (non-member cannot access project data)
|
|
|
|
### E2E Tests (Playwright)
|
|
- auth.spec.ts (login, logout, protected screen)
|
|
- project-management.spec.ts (create, edit, member add/remove, archive)
|
|
|
|
## Dependent Libraries
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"next": "15",
|
|
"react": "19",
|
|
"react-dom": "19",
|
|
"better-sqlite3": "^11",
|
|
"bcrypt": "^5",
|
|
"react-markdown": "^9",
|
|
"remark-gfm": "^4",
|
|
"rehype-sanitize": "^6"
|
|
},
|
|
"devDependencies": {
|
|
"tailwindcss": "^3",
|
|
"@types/better-sqlite3": "^7",
|
|
"@types/bcrypt": "^5",
|
|
"@playwright/test": "^1",
|
|
"tsx": "^4"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
app/
|
|
api/auth/{register,login,logout,me}/route.ts
|
|
api/users/me/route.ts
|
|
api/projects/route.ts
|
|
api/projects/[projectId]/route.ts
|
|
api/projects/[projectId]/members/route.ts
|
|
api/projects/[projectId]/members/[userId]/route.ts
|
|
api/admin/migrations/route.ts
|
|
login/page.tsx
|
|
profile/page.tsx
|
|
dashboard/page.tsx
|
|
projects/[projectId]/{page,members,settings}.tsx
|
|
layout.tsx, globals.css
|
|
lib/
|
|
db/{sqlite.ts, migrator.ts, run-migrations.ts, migrations/001_initial.sql}
|
|
auth/{session.ts, getCurrentUser.ts}
|
|
types/*.ts
|
|
validators/{userValidator.ts, projectValidator.ts}
|
|
repositories/{UserRepository,ProjectRepository,ProjectMemberRepository}.ts
|
|
services/{AuthService,ProjectService}.ts
|
|
components/layout/{Header,Sidebar,ProjectNav}.tsx
|
|
tests/unit/..., tests/integration/..., tests/e2e/...
|
|
```
|
|
|
|
## Implementation Order
|
|
|
|
1. M1 (branch feature/m1-setup): Next.js setup, deps, config, dir structure, remove boilerplate → merge to main
|
|
2. M2 (branch feature/m2-db-foundation): SQL wrapper, migrator, schema, types, migration API, unit tests → merge to main
|
|
3. M3 (branch feature/m3-auth-user): UserRepository, AuthService, session, validators, auth API, login/profile pages, unit + e2e → merge to main
|
|
4. M4 (branch feature/m4-project-member): Project/Member repos, ProjectService, project API, dashboard/members/settings pages, unit + integration + e2e → merge to main
|
|
|
|
## Security Considerations
|
|
|
|
- Passwords hashed with bcrypt (never plaintext)
|
|
- All SQL parameter-bound (no string concatenation)
|
|
- Auth required on all protected routes (except /api/auth/register, /api/auth/login)
|
|
- Project access requires isMember check
|
|
- Admin features require role='system_admin'
|
|
- .env not committed; secrets via environment
|
|
|
|
## Performance Considerations
|
|
|
|
- SQLite WAL mode for read/write concurrency
|
|
- Pagination on list endpoints
|
|
- Singleton DB connection
|
|
|
|
## Future Extensibility
|
|
|
|
- Repository pattern allows adding tables without changing wrapper
|
|
- SseEvent type extensible (M8)
|
|
- NotificationService/ActivityLogService hooks prepared for M5 (ProjectService.addMember will call notification in M5)
|