application-form-7/prompts/001-flask-job-application-system.md

<objective>
Build a complete, stateful Flask web application for job applications with email-based resume functionality, multi-step form validation, and file uploads. This system will be linked from external job postings and must handle the entire application lifecycle from initial contact through final submission, with the ability to resume at any point.

The application serves as a standalone application form that external job postings link to, passing a job name parameter to track which position the applicant is applying for.
</objective>

<context>
This is a simple but robust job application system that prioritizes:
- Accessibility and simplicity (minimal CSS, no JavaScript required)
- Stateful workflow that can be resumed via email link
- File-based persistence (YAML + file storage, no database)
- German language interface for all user-facing content
- Clean validation at each step

The application workflow consists of 5 distinct pages:
1. Email capture + session creation
2. Basic personal information
3. Motivation and qualification questions
4. Document uploads (CV, cover letter, etc.)
5. Final submission

Tech stack: Python 3, Flask, YAML for data serialization, minimal CSS, no JavaScript
</context>

<requirements>

<workflow>
**Page 1: Email Capture & Session Initialization**
- Accept URL parameter: `/apply?job=JuniorMarketingAssistant`
- Prompt for email address
- Generate unique session ID (UUID)
- Store session data: email, job name, session ID, timestamp
- Send email with resume link containing session ID
- Redirect to Page 2 on submit
- Resume link format: `/resume/{session_id}` redirects to appropriate page

**Page 2: Basic Personal Information**
Required fields:
- Name (string, max 255 chars)
- Firstname (string, max 255 chars)
- Addresse (string, max 255 chars)
- ZIP Code (integer, max 10 digits)
- City (string, max 255 chars)
- Phone number (international format validation)
- Year of birth (4-digit integer, e.g., 1982)

Optional fields:
- Civil status (string, max 255 chars)

**Page 3: Motivation & Qualifications**
Four textarea fields (all optional but length-limited):
1. "Bitte beschreiben Sie Ihre aktuelle berufliche Situation."
2. "Was motiviert Sie, für uns zu arbeiten?"
3. "Bitte nennen Sie uns Ihre besonderen Qualifikationen für diese Stelle."
4. "Was sind Ihre Gehaltsvorstellungen (brutto, basierend auf Vollzeitbeschäftigung)?"

Each textarea limited to ~3000 characters (approximately one A4 page)

**Page 4: Document Upload**
- Allow up to 3 document uploads
- Maximum 4 MB per document
- Preferred format: PDF
- Display uploaded documents with remove option
- Store in `./applications/{session_id}/attachments/` folder
- Submit button with clear explanation:
  - "Bewerbung absenden" button
  - Note that application will be submitted but can be modified while active

**Page 5: Confirmation**
- Display success message
- Confirm application details
- Provide information about next steps
</workflow>

<technical_specifications>
**Data Storage**
- Store application data in YAML files: `./applications/{session_id}/data.yaml`
- Store attachments in: `./applications/{session_id}/attachments/`
- Each application gets its own folder structure
- YAML structure should include: session_id, job_name, email, timestamp, current_page, personal_info, motivation_answers, uploaded_files

**Session Management**
- Generate cryptographically secure UUIDs for session IDs
- Track current page/progress in session data
- Allow resume at any point via `/resume/{session_id}`
- Validate session exists before allowing access

**Email Functionality**
- Send resume link immediately after email capture
- Email subject: "Ihre Bewerbung bei [Company] - Link zum Fortsetzen"
- Email body: German text with resume link
- Use Flask-Mail or similar for email sending
- Email configuration should be environment-based

**Validation Requirements**
- Email: Valid email format
- Phone: International format (e.g., +41 79 123 45 67)
- ZIP Code: Numeric, max 10 digits
- Year of birth: 4 digits, reasonable range (1940-2010)
- Text areas: Max ~3000 characters each
- File uploads: Max 4 MB, count ≤ 3
- Display clear, German error messages for all validation failures

**German Language**
All labels, messages, and instructions must be in German:
- Form labels and placeholders
- Error messages
- Button text
- Email content
- Success/confirmation messages
</technical_specifications>

</requirements>

<implementation>

**Project Structure**
Create the following structure:
```
./
├── app.py                 # Main Flask application
├── templates/
│   ├── page1_email.html
│   ├── page2_personal.html
│   ├── page3_motivation.html
│   ├── page4_upload.html
│   └── page5_confirmation.html
├── static/
│   └── style.css         # Minimal CSS for basic styling
├── applications/         # Created dynamically, stores all application data
├── config.py             # Configuration (email settings, etc.)
└── requirements.txt      # Python dependencies
```

**Key Implementation Details**

1. **Session Flow**: After each successful form submission, update the YAML file with current progress and redirect to next page. The `current_page` field tracks progress for resume functionality.

2. **Resume Functionality**: The `/resume/{session_id}` route should:
   - Load session data from YAML
   - Check `current_page` value
   - Redirect to appropriate page with form pre-filled

3. **Form Pre-filling**: When resuming, populate form fields from existing YAML data so users can review/modify their answers.

4. **File Upload Security**:
   - Validate file extensions (prefer PDF but allow common formats)
   - Sanitize filenames to prevent path traversal
   - Store with secure filenames (e.g., `{timestamp}_{sanitized_original_name}`)

5. **Email Configuration**: Use environment variables for email credentials. Include a `.env.example` file showing required configuration.

6. **Error Handling**:
   - Graceful handling of missing sessions
   - Clear error messages in German for validation failures
   - File system error handling (disk space, permissions)

7. **CSS Approach**: Keep styling minimal and accessible:
   - Clear visual hierarchy
   - Good contrast ratios
   - Responsive without requiring JavaScript
   - Form field spacing and readability
   - Clear focus states for keyboard navigation

**What to Avoid and Why**:
- No JavaScript: Keeps the application accessible and simple, works without client-side execution
- No database: File-based storage is simpler for small-scale applications and easier to deploy
- No client-side validation: Server-side only ensures security and works in all environments
- Avoid complex frameworks: Flask alone is sufficient, reducing dependencies and complexity
</implementation>

<output>
Create the following files with relative paths:

1. `./app.py` - Main Flask application with all routes and logic
2. `./config.py` - Configuration management (email settings, file limits, etc.)
3. `./requirements.txt` - Python dependencies (Flask, PyYAML, Flask-Mail, python-dotenv)
4. `./templates/page1_email.html` - Email capture page (German)
5. `./templates/page2_personal.html` - Personal information form (German)
6. `./templates/page3_motivation.html` - Motivation questions (German)
7. `./templates/page4_upload.html` - File upload interface (German)
8. `./templates/page5_confirmation.html` - Success confirmation (German)
9. `./static/style.css` - Minimal, accessible CSS
10. `./.env.example` - Example environment configuration
11. `./README.md` - Setup and deployment instructions in English

The `./applications/` directory will be created automatically by the application when the first application is submitted.
</output>

<verification>
Before declaring complete, verify your implementation:

1. **Session Flow Test**: Simulate the complete workflow from email capture through final submission
2. **Resume Test**: Verify that the resume link correctly redirects to the appropriate page with pre-filled data
3. **Validation Test**: Test all validation rules (email format, phone format, file size, character limits)
4. **File Upload Test**: Verify files are stored correctly and can be removed
5. **German Language**: Confirm all user-facing text is in German
6. **YAML Storage**: Verify YAML files are created correctly and data persists
7. **Error Handling**: Test with invalid session IDs and edge cases

Run the Flask application locally and test each page transition to ensure the stateful workflow functions correctly.
</verification>

<success_criteria>
- All 5 pages implemented with proper routing
- Session management with unique IDs working
- Email sending with resume link functional
- All validation rules implemented with German error messages
- File uploads working with size and count limits
- Data persists in YAML format correctly
- Resume functionality allows picking up at any page
- Form pre-filling works when resuming
- All user-facing content is in German
- Minimal CSS provides clean, accessible interface
- No JavaScript required for any functionality
- README includes clear setup instructions
</success_criteria>