CodexMiroir is a voice-first, minimalistic task management system implementing the "Spiegelkodex" philosophy - a FIFO (First-In-First-Out) approach that enforces focus by showing only the current task prominently. The system operates in German and supports both professional and private task management with distinct visual themes.
- Focus-enforcing: Only current task is prominently displayed
- FIFO principle: Strict first-in-first-out task ordering, no manual reordering
- Voice-first: Primary interaction through German voice commands
- Dual-mode: Professional (dark theme) and Private (light theme) separation
- Minimalistic: No complex animations, drag-and-drop, or overwhelming features
- Frontend: Progressive Web App (PWA) with Vanilla JS, AlpineJS, and modern CSS
- Backend: Azure Functions v4 (Node.js 18+) + Azure Blob Storage
- AI Integration: OpenAI GPT-3.5/4 for German voice command processing
- Voice: Web Speech API with fallback to text input
- Storage: Markdown files with YAML frontmatter in Azure Blob Storage
/
├── manifest.json # PWA manifest
├── sw.js # Service worker
├── frontend/ # Frontend source files (PWA entry point)
│ ├── index.html # Main PWA HTML
│ ├── app.js # Main PWA application
│ ├── codex-api.js # API client
│ ├── token-manager.js # Token management
│ └── styles.css # Application styles
├── codex/ # Azure Functions backend
│ ├── index.js # Main API router
│ ├── markdownCrud.js # CRUD operations
│ ├── llmActions.js # AI/voice processing
│ └── helpers.js # Utility functions
├── static/ # Static file serving function
├── documentation/ # Complete project documentation
└── __tests__/ # Jest test suite
- Primary Language: German (de-DE) for UI, voice commands, and responses
- Date Format: Always use European format
dd.mm.yyyy [HH:MM]
- Voice Commands: Natural German language processing with fallbacks
- Code Comments: English for technical documentation, German for user-facing content
- Glossar: See arc42 documentation for complete terminology definitions
- Current implementation uses JavaScript with JSDoc comments
- Prefer clear interfaces and type documentation in comments
- Use validation functions for runtime type checking
- Note: Legacy
/shared/schema.ts
contains old PostgreSQL schema - current implementation uses Markdown files
- Use vanilla JavaScript with modern ES6+ features
- Progressive Web App (PWA) patterns for offline functionality
- AlpineJS for reactive components where needed
- Modern CSS with utility-first approach where applicable
- Implement responsive design with mobile-first approach
- Ensure accessibility (ARIA labels, keyboard navigation)
- Token-based authentication stored in localStorage
- Supported Commands:
- "Erstelle Aufgabe: [Titel]" - Create new task
- "Aktuelle Aufgabe abschließen" - Complete current task
- "Aufgabe verschieben" - Push task to end
- "Status anzeigen" - Show current status
- Use Web Speech API with graceful degradation
- Provide visual feedback for voice recognition states
- Implement pattern matching fallbacks when AI is unavailable
- Single function with multiple actions via query parameter (
?action=...
)
- Token-based Authentication:
/api/codex/{token}?action=...
- Endpoints:
createTask
- Create new task with Markdown file and current.md entry
completeTask
- Mark task complete, move to archive.md
pushToEnd
- Move task to end of queue (when not workable)
report
- Get statistics for a week/list combination
when
- Find position of specific task in queue
processCommand
- Process German voice commands with AI/fallback
decomposeTask
- Break large tasks into 3.5h chunks using AI
getCurrentTask
- Get voice-optimized current task information
- Use Azure Blob Storage for persistent data as Markdown files
- Implement proper error handling and logging
- Token validation via URL path parameter
- Follow serverless best practices (stateless, idempotent)
- Storage Format: Markdown files with YAML frontmatter
- Authentication: Token-based user separation (
users/{token}/codex-miroir/
)
- Task Structure: Each task is a separate
.md
file
---
id: T-0123456789
list: pro # 'pro' | 'priv'
title: "API Spec"
status: geplant # geplant | aktiv | abgeschlossen
created_at: 23.09.2025 09:12
scheduled_slot: 2025-W39-Tue-AM
duration_slots: 1
deadline: 30.09.2025 16:00
project: ""
azure_devops: ""
requester: ""
category_pro: programmierung # meeting | programmierung
category_priv: "" # haushalt | projekt
---
## Notiz
Task details...
## Verlauf
- 23.09.2025 09:15 → geplant in `2025-W39-Tue-AM`
- Organization: User-isolated storage paths
- Current Tasks: Tracked in
current.md
with weekly tables
- Completed Tasks: Archived in
archive.md
with completion data
- Professional Mode: Monday-Friday, 2 slots/day (9-12:30, 13:30-17:00)
- Private Mode: Monday-Friday evenings + weekends
- Slot Duration: Exactly 3.5 hours per slot
- Slot IDs: Format
YYYY-Www-DOW-AM/PM
(ISO week format)
- Centralize API calls in
/frontend/codex-api.js
- Use proper token-based authentication
- Implement retry logic and error handling
- Use modern fetch API with proper error handling
// Example PWA component pattern
class TaskManager {
constructor() {
this.api = window.codexApi;
this.init();
}
async init() {
this.setupEventListeners();
await this.loadTasks();
}
setupEventListeners() {
// Event handling logic
}
}
- Primary processing via OpenAI GPT-4 API
- Fallback to regex pattern matching
- Response format includes intent, confidence, and parameters
- Support for context-aware processing
- Graceful degradation when AI services are unavailable
- User-friendly German error messages
- Proper logging for debugging
- Fallback mechanisms for all critical functionality
- Format:
YYYY-MM-DD--<id>-<slug>.md
- Example:
2025-09-23--T-0123-api-spec.md
- Vanilla JS classes for application components:
TaskManager
- kebab-case for utility files:
codex-api.js
, token-manager.js
- Single
index.js
file with multiple exported actions
- Clear function naming:
createTask
, completeTask
, processCommand
- Test voice command recognition with German phrases
- Validate time slot calculations and FIFO ordering
- Test offline/fallback functionality (Pattern-Matching when OpenAI unavailable)
- Verify proper Markdown file generation and parsing
- Test token-based authentication and user isolation
- Validate dual-mode theme switching (professional/private)
- Test PWA offline capabilities and service worker
# Azure Functions
AZURE_BLOB_CONN=<connection-string>
BLOB_CONTAINER=codex-miroir
OPENAI_API_KEY=<openai-key> # Optional, has fallback
# Note: API_KEY is no longer used - replaced by token-based auth
- API responses should be < 200ms for CRUD operations
- Voice recognition should process within 2 seconds
- UI updates should be < 100ms
- Implement proper loading states and optimistic updates
- Use React.memo for expensive components → Use proper event delegation and DOM optimization
- Minimize bundle size with proper tree shaking → Minimize JS/CSS bundle sizes
- Use temperature 0.3 for consistent command parsing
- Implement proper prompt engineering for German context
- Always provide fallback for AI failures (Pattern-Matching)
- Cache common responses to reduce API calls
- Respect OpenAI rate limits and usage policies
- Risk Mitigation: Implement robust fallback mechanisms for OpenAI API outages
- Support keyboard navigation throughout
- Provide proper ARIA labels and descriptions
- Support screen readers
- Ensure sufficient color contrast
- Provide alternative text input when voice isn't available
- Update relevant documentation when changing functionality
- Include German examples for voice commands
- Document API endpoints with request/response examples
- Maintain deployment guides for Azure services
- Keep README files current with setup instructions
- Follow arc42 architecture documentation standard
- Important: Refer to
/documentation/arc42.md
for complete system architecture
These files/directories must never be deleted as they are automatically generated or critical for CI/CD:
codequality/report.md
- Automatically generated SonarCloud quality report. This file is created and updated by the GitHub Actions workflow (.github/workflows/sonarcloud-quality.yml
). While it's tracked in git, it's regenerated on every CI run and should never be manually deleted.
.github/workflows/
- CI/CD workflow definitions
documentation/arc42.md
- Primary architecture documentation
The project has been fully migrated to Azure Functions-only architecture with PWA frontend. Previous architecture included:
- Removed: React/TypeScript frontend stack
- Removed: Express server backend
- Removed: API_KEY authentication (replaced by token-based)
- Removed: PostgreSQL database (replaced by Markdown files)
Current Focus:
- Azure Functions backend (
/codex/
)
- Progressive Web App frontend (
/frontend/
)
- Voice-first user experience
- Token-based user separation
When working on this project, prioritize the voice-first experience, maintain the focus-enforcing FIFO principle, and ensure all user-facing content supports German language properly.