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

-- 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