OCR/openspec/specs/frontend-ui/spec.md

frontend-ui Specification

Purpose

TBD - created by archiving change refactor-frontend-ux-i18n. Update Purpose after archive.

Requirements

Requirement: Minimal Login Page Design

The login page SHALL use a professional minimal design style that is consistent with the rest of the application.

The login page SHALL NOT include:

• Animated gradient backgrounds
• Floating decorative elements (orbs, particles)
• Pulsing or floating animations
• Marketing claims or statistics
• Feature promotion sections

The login page SHALL include:

• Centered login form with clean white card
• Application logo and name
• Username and password input fields
• Login button with loading state
• Error message display area
• Simple solid color background

Scenario: Login page renders with minimal design

• WHEN user navigates to the login page
• THEN the page displays a centered login form
• AND no animated decorative elements are visible
• AND no marketing content is displayed

Scenario: Login form visual consistency

• WHEN comparing login page to internal pages
• THEN the visual style (colors, typography, spacing) is consistent

---

Requirement: Multi-language Support

The application SHALL support multiple languages with user-selectable language preference.

Supported languages:

• Traditional Chinese (zh-TW) - Default
• English (en-US)

The language selection SHALL be persisted in localStorage and restored on page reload.

Scenario: Language switcher available

• WHEN user is logged in and viewing any page
• THEN a language switcher component is visible in the top navigation bar

Scenario: Switch to English

• WHEN user selects English from the language switcher
• THEN all UI text immediately changes to English
• AND the preference is saved to localStorage

Scenario: Switch to Traditional Chinese

• WHEN user selects Traditional Chinese from the language switcher
• THEN all UI text immediately changes to Traditional Chinese
• AND the preference is saved to localStorage

Scenario: Language preference persistence

• WHEN user has previously selected a language preference
• AND user reloads the page or returns later
• THEN the application displays in the previously selected language

---

Requirement: Accurate Product Description

All user-facing text SHALL accurately describe the product capabilities without exaggeration.

The application SHALL NOT display:

• Unverified accuracy percentages (e.g., "99% accuracy")
• Superlative marketing claims (e.g., "lightning fast", "enterprise-grade")
• Unsubstantiated statistics
• Comparative claims without evidence

The application MAY display:

• Factual feature descriptions
• Supported file formats
• Authentication method information

Scenario: Login page displays factual information

• WHEN user views the login page
• THEN only factual product information is displayed
• AND no unverified claims are present

Scenario: Feature descriptions are accurate

• WHEN any page describes product features
• THEN the descriptions are factual and verifiable

Requirement: Batch Processing Support

The system SHALL support batch processing of multiple uploaded files with a single configuration.

After uploading multiple files, the user SHALL be able to:

• Configure processing settings once for all files
• Start processing all files with one action
• Monitor progress of all files in a unified view

Scenario: Multiple files uploaded

• WHEN user uploads multiple files
• AND navigates to processing page
• THEN the system displays batch processing mode
• AND shows all pending tasks in a list

Scenario: Batch configuration

• WHEN user is in batch processing mode
• THEN user can select a processing strategy (auto/OCR/Direct)
• AND user can configure layout model for OCR tasks
• AND user can configure preprocessing for OCR tasks
• AND settings apply to all applicable tasks

---

Requirement: Batch Processing Strategy

The system SHALL support three batch processing strategies:

1. Auto Detection (default): System analyzes each file and selects optimal track
2. Force OCR: All files processed with OCR track
3. Force Direct: All PDF files processed with Direct track

Scenario: Auto detection strategy

• WHEN user selects auto detection strategy
• THEN the system analyzes each file before processing
• AND assigns OCR or Direct track based on file characteristics

Scenario: Force OCR strategy

• WHEN user selects force OCR strategy
• THEN all files are processed using OCR track
• AND layout model and preprocessing settings are applied

Scenario: Force Direct strategy

• WHEN user selects force Direct strategy
• AND file is a PDF
• THEN the file is processed using Direct track

---

Requirement: Parallel Processing Limits

The system SHALL enforce different parallelism limits based on processing track:

• Direct Track: Maximum 5 concurrent tasks (CPU-based)
• OCR Track: Maximum 1 concurrent task (GPU VRAM constraint)

Direct and OCR tasks MAY run simultaneously as they use different resources.

Scenario: Direct track parallelism

• WHEN batch contains multiple Direct track tasks
• THEN up to 5 tasks process concurrently
• AND remaining tasks wait in queue

Scenario: OCR track serialization

• WHEN batch contains multiple OCR track tasks
• THEN only 1 task processes at a time
• AND remaining tasks wait in queue

Scenario: Mixed track processing

• WHEN batch contains both Direct and OCR tasks
• THEN Direct tasks run in parallel pool (max 5)
• AND OCR tasks run in serial queue (max 1)
• AND both pools operate simultaneously

---

Requirement: Batch Progress Display

The system SHALL display unified progress for batch processing.

Progress display SHALL include:

• Overall progress (completed / total)
• Count by status (processing, completed, failed)
• Individual task status list
• Estimated time remaining (optional)

Scenario: Batch progress monitoring

• WHEN batch processing is in progress
• THEN user sees overall completion percentage
• AND user sees count of tasks in each status
• AND user sees status of each individual task

Scenario: Batch completion

• WHEN all tasks in batch are completed or failed
• THEN user sees final summary
• AND user can navigate to results page