Yasser Harbi

# Project Goal

Build a simple, modern web application called **Course Enrollment Portal** using Python, Flask, HTMX, and SQLite.

**Features:**
- Display a list of available courses (title, description, instructor, duration) on a grid.
- Allow users to select a course and submit a request/enrollment form (name, email, phone, message/motivation) on a popup.
- After submission, show a success message and list all enrollment requests (admin view-like, simple for demo).
- Use HTMX for dynamic interactions: partial page updates, no full reloads, smooth UX with minimal  JavaScript.
- Style the app nicely using Tailwind CSS (via CDN for simplicity).
- Store data in SQLite via Flask-SQLAlchemy.

**User Flow:**
1. Home page: Shows list of courses in a grid/cards responsive.
2. User clicks "Enroll" on a course → HTMX loads the enrollment form (pre-filled with selected course) choose better UX for filling the form on a popup without loading another page.
3. User fills and submits form → HTMX submits, shows success message, and optionally updates a requests list.

# Tech Stack Requirements
- **Dependency Management**: Use **Poetry** exclusively (no pip or virtualenv directly) install poetry directly on system for easy use.
- **Framework**: **Flask** (latest compatible version).
- **Database**: **Flask-SQLAlchemy** with SQLite backend.
- **Frontend Interactivity**: **HTMX** (via CDN) for dynamic updates.
- **Styling**: Tailwind CSS (via CDN).
- Optional: Use `flask-htmx` extension for easier partial detection if helpful.
- Python version: Target Python 3.13+ (current as of late 2025).

# Best Practices to Follow
- Use application factory pattern in `__init__.py`.
- Organize with Blueprints if needed (at least one for main views).
- Separate templates into base.html + partials (for HTMX).
- Validate form inputs (server-side).
- Handle errors gracefully (flash messages).
- Seed the database with 5-10 sample courses on first run.
- Project structure inspired by Poetry defaults + Flask recommendations.

# Recommended Project Structure
├── pyproject.toml
├── README.md
├── build_environment.md          # For tracking task progress
├── src/
│   └── course_portal/
│       ├── init.py          # App factory, db init
│       ├── models.py            # SQLAlchemy models (Course, EnrollmentRequest)
│       ├── routes.py            # Or blueprints/views
│       ├── forms.py             # Optional WTForms if needed, else manual validation
│       ├── templates/
│       │   ├── base.html
│       │   ├── index.html
│       │   ├── partials/
│       │   │   ├── course_list.html
│       │   │   ├── enrollment_form.html
│       │   │   └── requests_list.html
│       └── static/                  # If needed for custom CSS/JS (minimal)
├── tests/                           # Add basic tests later
└── instance/                        # SQLite db will be here

# Step-by-Step Tasks
Create a file `build_environment.md` at the project root to track progress with checklists.

- [ ] **Initialize Project**
  - Run `poetry new course-enrollment-portal --src` (uses src layout).
  - cd into the project.
  - Add dependencies: `poetry add flask flask-sqlalchemy`
  - Add HTMX/Tailwind via CDN in templates (no need to add as deps).
  - Optional: `poetry add flask-htmx`

- [ ] **Set Up Flask App**
  - Create application factory in `src/course_portal/__init__.py`.
  - Configure SQLite db (`instance/course_portal.sqlite`).
  - Initialize db in a command or on first run.

- [ ] **Define Models**
  - In `models.py`: Course (id, title, description, instructor, duration).
  - EnrollmentRequest (id, course_id FK, name, email, phone, message, timestamp).

- [ ] **Create Database Seed**
  - Add a function/script to populate 5-10 sample courses if db empty.

- [ ] **Build Templates**
  - `base.html`: Include Tailwind CDN, HTMX CDN, basic layout (header, main container).
  - `index.html`: Extend base, include course list partial.
  - Partials for HTMX swaps: course cards, form, success message.

- [ ] **Implement Routes**
  - `/`: GET - Render full page with course list.
  - `/courses`: GET - Return partial course list (for HTMX refresh if needed).
  - `/enroll/<course_id>`: GET - Return partial enrollment form.
  - `/enroll`: POST - Validate, save request, return success partial + updated requests list.
  - `/requests`: GET - Return partial list of all enrollment requests.

- [ ] **Add HTMX Interactions**
  - Course cards: hx-get to load form into a div.
  - Form: hx-post, hx-target to update a result div with success or errors.
  - Use hx-swap="innerHTML" or "outerHTML" as needed.

- [ ] **Add Validation & Feedback**
  - Server-side check for required fields, valid email.
  - Use Flask flash or return error partials.

- [ ] **Run & Test**
  - Add script in pyproject.toml: `poetry run flask --app src/course_portal run --debug`
  - Or use `flask run` with FLASK_APP set.
  - Manually test all flows.
  - Ensure db seeds on first run.

- [ ] **Final Polish**
  - Add README with setup/run instructions.
  - Basic error handling (404, 500).
  - Make it responsive with Tailwind.

# Progress Tracking
- After completing each major task above, update `build_environment.md` with:
  - [x] Task description
  - Notes on what was implemented.
- Once all tasks are done, mark the project as complete.

# General Guidelines
1. Always provide clean, commented code.
2. If unclear on any feature, suggest a simple implementation.
3. Output code changes file-by-file with full paths.
4. minimal JavaScript for better UX only.
5. Prioritize simplicity and functionality over perfection.
6. After each step, confirm it works before proceeding.

Follow these instructions to build a fully functional, interactive web app!

You are a DevOps expert setting up a Python development environment using Docker and VS Code Remote Containers.

Your task is to provide and run Docker commands for a lightweight Python development container based on the official python latest slim-bookworm image.

Key requirements:
- Use interactive mode with a bash shell that does not exit immediately.
- Override the default command to keep the container running indefinitely (use sleep infinity or similar) do not remove the container after running.
- Name it py-dev-container
- Mount the current working directory (.) as a volume to /workspace inside the container (read-write).
- Run the container as a non-root user named 'vscode' with UID 1000 for seamless compatibility with VS Code Remote - Containers extension.
- Install essential development tools inside the container if needed (git, curl, build-essential, etc.), but only via runtime commands if necessary.
- Do not create any files on the host or inside the container beyond what's required for running.
- Make the container suitable for attaching VS Code remotely (Remote - Containers: Attach to Running Container) to enable further Python development, debugging, and extension usage.

Provide:
1. The docker pull command (if needed).
2. The full docker run command with all flags.
3. Instructions on how to attach VS Code to this running container for development.

Assume the user is in the root folder of their Python project on the host.