Meeting_Assistant/openspec/specs/middleware/spec.md

middleware Specification

Purpose

TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.

Requirements

Requirement: FastAPI Server Configuration

The middleware server SHALL be implemented using Python FastAPI framework with comprehensive environment-based configuration supporting standalone deployment.

Scenario: Server startup with valid configuration

• WHEN the server starts with valid .env file containing all required variables (DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME, DIFY_API_URL, DIFY_API_KEY, AUTH_API_URL)
• THEN the server SHALL start successfully and accept connections on the configured BACKEND_HOST and BACKEND_PORT

Scenario: Server startup with missing configuration

• WHEN the server starts with missing required environment variables
• THEN the server SHALL fail to start with descriptive error message

Scenario: Server startup with optional configuration

• WHEN optional environment variables (BACKEND_PORT, DB_POOL_SIZE, etc.) are not set
• THEN the server SHALL use sensible defaults and start normally

Requirement: Database Connection Pool

The middleware server SHALL maintain a configurable connection pool to the MySQL database using environment variables.

Scenario: Database connection success

• WHEN the server connects to MySQL with valid credentials from environment
• THEN a connection pool SHALL be established with DB_POOL_SIZE connections

Scenario: Database connection failure

• WHEN the database is unreachable
• THEN the server SHALL return HTTP 503 with error details for affected endpoints

Requirement: Table Initialization

The middleware server SHALL ensure all required tables exist on startup with the meeting_ prefix.

Scenario: Tables created on first run

• WHEN the server starts and tables do not exist
• THEN the server SHALL create meeting_users, meeting_records, meeting_conclusions, and meeting_action_items tables

Scenario: Tables already exist

• WHEN the server starts and tables already exist
• THEN the server SHALL skip table creation and continue normally

Requirement: CORS Configuration

The middleware server SHALL allow cross-origin requests from all origins to support Electron desktop application clients.

Scenario: CORS preflight request

• WHEN any client sends OPTIONS request
• THEN the server SHALL respond with CORS headers allowing the request (allow_origins=["*"])

Requirement: Backend Server Configuration

The middleware server SHALL support configurable host and port through environment variables for flexible deployment.

Scenario: Custom port binding

• WHEN BACKEND_PORT environment variable is set to 9000
• THEN the server SHALL listen on port 9000

Scenario: Production host binding

• WHEN BACKEND_HOST is set to 0.0.0.0
• THEN the server SHALL accept connections from any network interface

Scenario: Default configuration

• WHEN BACKEND_HOST and BACKEND_PORT are not set
• THEN the server SHALL default to 0.0.0.0:8000

Requirement: Timeout Configuration

The middleware server SHALL support configurable timeout values for different operations through environment variables.

Scenario: File upload timeout

• WHEN UPLOAD_TIMEOUT is set to 900000 (15 minutes)
• THEN file upload operations SHALL allow up to 15 minutes before timeout

Scenario: LLM processing timeout

• WHEN LLM_TIMEOUT is set to 180000 (3 minutes)
• THEN Dify LLM summarization operations SHALL allow up to 3 minutes before timeout

Scenario: Dify STT timeout

• WHEN DIFY_STT_TIMEOUT is set to 600000 (10 minutes)
• THEN Dify STT audio transcription per chunk SHALL allow up to 10 minutes before timeout

Scenario: Authentication timeout

• WHEN AUTH_TIMEOUT is set to 60000 (1 minute)
• THEN authentication API calls SHALL allow up to 1 minute before timeout

Requirement: File Path Configuration

The middleware server SHALL support configurable directory paths for templates and records.

Scenario: Custom template directory

• WHEN TEMPLATE_DIR environment variable is set to /data/templates
• THEN Excel templates SHALL be loaded from /data/templates

Scenario: Custom record directory

• WHEN RECORD_DIR environment variable is set to /data/records
• THEN exported meeting records SHALL be saved to /data/records

Scenario: Relative path resolution

• WHEN directory paths are relative
• THEN they SHALL be resolved relative to the backend application root

Requirement: Frontend Environment Configuration

The frontend Electron application SHALL support environment-based API URL configuration for connecting to deployed backend.

Scenario: Custom API URL in production build

• WHEN VITE_API_BASE_URL is set to http://192.168.1.100:8000/api during build
• THEN the built Electron app SHALL connect to http://192.168.1.100:8000/api

Scenario: Default API URL in development

• WHEN VITE_API_BASE_URL is not set
• THEN the frontend SHALL default to http://localhost:8000/api

Requirement: Sidecar Whisper Configuration

The Electron frontend's Sidecar (local Whisper transcription service) SHALL support environment-based model configuration.

Scenario: Custom Whisper model

• WHEN WHISPER_MODEL environment variable is set to "large"
• THEN the Sidecar SHALL load the large Whisper model for transcription

Scenario: GPU acceleration

• WHEN WHISPER_DEVICE is set to "cuda" and WHISPER_COMPUTE is set to "float16"
• THEN the Sidecar SHALL use GPU for faster transcription

Scenario: Default CPU mode

• WHEN WHISPER_DEVICE is not set
• THEN the Sidecar SHALL default to CPU with int8 compute type

Requirement: Environment Example Files

The project SHALL provide example environment files documenting all configuration options.

Scenario: Backend environment example

• WHEN developer sets up backend
• THEN backend/.env.example SHALL list all environment variables with descriptions and example values (without sensitive data)

Scenario: Frontend environment example

• WHEN developer sets up frontend
• THEN client/.env.example SHALL list all VITE_ prefixed and WHISPER_ prefixed environment variables with descriptions