CodexMiroir - GitHub Copilot Instructions

Project Overview

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.

Core Philosophy

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

Architecture

Tech Stack

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

Project Structure

/
├── 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

Development Guidelines

Language and Localization

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

TypeScript Standards

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

Frontend Guidelines

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

Voice Integration

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

Azure Functions Backend

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)

Data Management

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

Time Slot System

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)

Coding Patterns

API Service Layer

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

Component Structure

// Example PWA component pattern
class TaskManager {
  constructor() {
    this.api = window.codexApi;
    this.init();
  }
  
  async init() {
    this.setupEventListeners();
    await this.loadTasks();
  }
  
  setupEventListeners() {
    // Event handling logic
  }
}

Voice Command Processing

Primary processing via OpenAI GPT-4 API
Fallback to regex pattern matching
Response format includes intent, confidence, and parameters
Support for context-aware processing

Error Handling

Graceful degradation when AI services are unavailable
User-friendly German error messages
Proper logging for debugging
Fallback mechanisms for all critical functionality

File Naming Conventions

Tasks

Format:
```
YYYY-MM-DD--<id>-<slug>.md
```
Example:
```
2025-09-23--T-0123-api-spec.md
```

Components

Vanilla JS classes for application components:
```
TaskManager
```
kebab-case for utility files:
```
codex-api.js
```
,
```
token-manager.js
```

Azure Functions

Single
```
index.js
```
file with multiple exported actions
Clear function naming:
```
createTask
```
,
```
completeTask
```
,
```
processCommand
```

Testing Considerations

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

Environment Variables

# 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

Performance Considerations

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

AI Integration Guidelines

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

Accessibility Requirements

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

Documentation Standards

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

Protected Files and Directories

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

Migration Notes

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.

CodexMiroir - GitHub Copilot Instructions

Project Overview

Core Philosophy

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

Architecture

Tech Stack

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

Project Structure

/
├── 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

Development Guidelines

Language and Localization

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

TypeScript Standards

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

Frontend Guidelines

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

Voice Integration

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

Azure Functions Backend

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)

Data Management

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

Time Slot System

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)

Coding Patterns

API Service Layer

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

Component Structure

// Example PWA component pattern
class TaskManager {
  constructor() {
    this.api = window.codexApi;
    this.init();
  }
  
  async init() {
    this.setupEventListeners();
    await this.loadTasks();
  }
  
  setupEventListeners() {
    // Event handling logic
  }
}

Voice Command Processing

Primary processing via OpenAI GPT-4 API
Fallback to regex pattern matching
Response format includes intent, confidence, and parameters
Support for context-aware processing

Error Handling

Graceful degradation when AI services are unavailable
User-friendly German error messages
Proper logging for debugging
Fallback mechanisms for all critical functionality

File Naming Conventions

Tasks

Format:
```
YYYY-MM-DD--<id>-<slug>.md
```
Example:
```
2025-09-23--T-0123-api-spec.md
```

Components

Vanilla JS classes for application components:
```
TaskManager
```
kebab-case for utility files:
```
codex-api.js
```
,
```
token-manager.js
```

Azure Functions

Single
```
index.js
```
file with multiple exported actions
Clear function naming:
```
createTask
```
,
```
completeTask
```
,
```
processCommand
```

Testing Considerations

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

Environment Variables

# 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

Performance Considerations

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

AI Integration Guidelines

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

Accessibility Requirements

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

Documentation Standards

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

Protected Files and Directories

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

Migration Notes

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.

CodexMiroir - GitHub Copilot Instructions

Related Skills

Nano Banana Pro

Markdown Converter

1password