Meeting_Assistant/openspec/changes/archive/2025-12-10-add-meeting-assistant-mvp/design.md

## Context
Building a meeting knowledge management system for enterprise users. The system must support offline transcription on standard hardware (i5/8GB), integrate with existing company authentication, and provide AI-powered summarization via Dify LLM.

**Stakeholders**: Enterprise meeting participants, meeting recorders, admin users (ymirliu@panjit.com.tw)

**Constraints**:
- Must run faster-whisper int8 on i5/8GB laptop
- DB credentials and API keys must stay server-side (security)
- All database tables prefixed with `meeting_`
- Output must support Traditional Chinese (繁體中文)

## Goals / Non-Goals

**Goals**:
- Deliver working MVP with all six capabilities
- Secure architecture with secrets in middleware only
- Offline-capable transcription
- Structured output with trackable action items

**Non-Goals**:
- Multi-language support beyond Traditional Chinese
- Real-time collaborative editing
- Mobile client
- Custom LLM model training

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     Electron Client                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Auth UI    │  │ Meeting UI  │  │  Transcription Engine   │  │
│  │  (Login)    │  │ (CRUD/Edit) │  │  (faster-whisper+OpenCC)│  │
│  └──────┬──────┘  └──────┬──────┘  └────────────┬────────────┘  │
└─────────┼────────────────┼──────────────────────┼───────────────┘
          │                │                      │
          │ HTTP           │ HTTP                 │ Local only
          ▼                ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                  FastAPI Middleware Server                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────┐  │
│  │ Auth Proxy  │  │Meeting CRUD │  │ Dify Proxy  │  │ Export │  │
│  │ POST /login │  │POST/GET/... │  │POST /ai/... │  │GET /:id│  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └───┬────┘  │
└─────────┼────────────────┼────────────────┼─────────────┼───────┘
          │                │                │             │
          ▼                ▼                ▼             │
┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│ PJ-Auth API  │  │    MySQL     │  │   Dify LLM   │     │
│  (Vercel)    │  │ (theaken.com)│  │(theaken.com) │     │
└──────────────┘  └──────────────┘  └──────────────┘     │
                                                         │
                                    ┌────────────────────┘
                                    ▼
                           ┌──────────────┐
                           │ Excel Template│
                           │ (openpyxl)   │
                           └──────────────┘
```

## Decisions

### Decision 1: Three-tier architecture with middleware
**Choice**: All external services accessed through FastAPI middleware
**Rationale**: Security requirement - DB credentials and API keys cannot be in Electron client
**Alternatives considered**:
- Direct client-to-service: Rejected due to credential exposure risk
- Serverless functions: More complex deployment for similar security

### Decision 2: Edge transcription in Electron
**Choice**: Run faster-whisper locally via Python sidecar (PyInstaller)
**Rationale**: Offline capability requirement; network latency unacceptable for real-time transcription
**Alternatives considered**:
- Cloud STT (Google/Azure): Requires network, latency issues
- WebAssembly whisper: Not mature enough for production

### Decision 3: MySQL with prefixed tables
**Choice**: Use shared MySQL instance with `meeting_` prefix
**Rationale**: Leverage existing infrastructure; prefix ensures isolation
**Alternatives considered**:
- Dedicated database: Overhead not justified for MVP
- SQLite: Doesn't support multi-user access

### Decision 4: Dify for LLM summarization
**Choice**: Use company Dify instance for AI features
**Rationale**: Already available infrastructure; structured JSON output support
**Alternatives considered**:
- Direct OpenAI API: Additional cost, no existing infrastructure
- Local LLM: Hardware constraints (i5/8GB insufficient)

## Risks / Trade-offs

| Risk | Impact | Mitigation |
|------|--------|------------|
| faster-whisper performance on i5/8GB | High | Use int8 quantization; test on target hardware early |
| Dify timeout on long transcripts | Medium | Implement chunking; add timeout handling with retry |
| Token expiry during long meetings | Medium | Implement auto-refresh interceptor in client |
| Network failure during save | Medium | Client-side queue with retry; local draft storage |

## Data Model

```sql
-- Tables all prefixed with meeting_

meeting_users (user_id, email, display_name, role, created_at)
meeting_records (meeting_id, uuid, subject, meeting_time, location,
                 chairperson, recorder, attendees, transcript_blob,
                 created_by, created_at)
meeting_conclusions (conclusion_id, meeting_id, content, system_code)
meeting_action_items (action_id, meeting_id, content, owner, due_date,
                      status, system_code)
```

**ID Formats**:
- Conclusions: `C-YYYYMMDD-XX` (e.g., C-20251210-01)
- Action Items: `A-YYYYMMDD-XX` (e.g., A-20251210-01)

## API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | /api/login | Proxy auth to PJ-Auth API |
| GET | /api/meetings | List meetings (filterable) |
| POST | /api/meetings | Create meeting |
| GET | /api/meetings/:id | Get meeting details |
| PUT | /api/meetings/:id | Update meeting |
| DELETE | /api/meetings/:id | Delete meeting |
| POST | /api/ai/summarize | Send transcript to Dify |
| GET | /api/meetings/:id/export | Generate Excel report |

## Open Questions
- None currently - PRD and SDD provide sufficient detail for MVP implementation