Instructions and plan

instructions.md

@@ -0,0 +1,149 @@
+Here’s a Claude Code prompt you can paste as-is and then tweak to taste:
+
+***
+
+You are an expert full‑stack developer.  
+Build a small but production‑ready web application to manage Shorewall firewall configurations with a browser frontend and a database backend. The app should NOT be a toy example but a clean, modular implementation that I can extend.
+
+## High‑level requirements
+
+- Purpose: Let users manage Shorewall configurations (zones, interfaces, policies, rules, masq, nat, hosts, etc.) in a web UI and generate the corresponding Shorewall config files on demand.
+- Stack:
+  - Backend: Python with FastAPI (preferred) or Django, using SQLAlchemy (or the framework’s ORM).
+  - Frontend: React + TypeScript with a simple component structure, using a UI library like MUI or Tailwind for basic styling.
+  - Database: PostgreSQL (but keep ORM models portable).
+- Architecture:
+  - Clean separation: frontend, backend API, and a “shorewall generator” module that knows how to render the text files.
+  - Use a REST or JSON API between frontend and backend.
+  - Use Docker Compose to run web + db.
+
+## Domain model and database
+
+Design a minimal but sensible schema to model Shorewall configs:
+
+- Core entities:
+  - Config: top‑level object (name, description, created_at, updated_at, is_active).
+  - Zone: belongs to Config (name, type, options).
+  - Interface: belongs to Config (name, zone_id FK, options).
+  - Policy: belongs to Config (src_zone_id, dst_zone_id, policy (ACCEPT/DROP/REJECT), log_level, comment, position/order).
+  - Rule: belongs to Config (action, src_zone_id, dst_zone_id, src_ip/cidr, dst_ip/cidr, proto, dport, sport, comment, position/order).
+  - Masq/NAT entry: belongs to Config (source_network, out_interface, to_address, comment).
+- Constraints:
+  - Foreign keys for relationships.
+  - Reasonable non‑null constraints.
+  - Basic uniqueness where it makes sense (e.g., zone name per config).
+
+Generate:
+- ORM models.
+- Database migration setup (e.g. Alembic) with an initial migration.
+
+## Shorewall file generation
+
+Implement a separate Python module that converts a Config from the database into Shorewall text files:
+
+- Target files (as functions or one class with multiple methods):
+  - zones
+  - interfaces
+  - policy
+  - rules
+  - masq
+- Each generator should:
+  - Accept a Config ID (or ORM object) and query all related entities.
+  - Produce a string that matches Shorewall file syntax, with headers like `#ZONE TYPE`, `#ACTION SOURCE DEST`, etc. [wiki.calculate-linux](https://wiki.calculate-linux.org/shorewall)
+  - Include a small comment header at the top with config name and a generated timestamp.
+- Implement one function that bundles all generated file contents into:
+  - Either a ZIP archive in memory, or
+  - A JSON object `{ zones: "...", interfaces: "...", policy: "...", rules: "...", masq: "..." }`
+  - We can later write this to `/etc/shorewall/` manually.
+
+## Backend API
+
+Use FastAPI (or Django REST) to implement these endpoints:
+
+- Auth (simple for now):
+  - POST /auth/register
+  - POST /auth/login
+  - Use JWT or simple session cookie; protect config management endpoints.
+- Config management:
+  - GET /configs
+  - POST /configs
+  - GET /configs/{id}
+  - PUT /configs/{id}
+  - DELETE /configs/{id}
+- Nested resources:
+  - CRUD for zones, interfaces, policies, rules, masq entries under a given config ID.
+- Generation:
+  - POST /configs/{id}/generate
+    - Returns the generated Shorewall files as JSON or as a ZIP download.
+- Implementation details:
+  - Pydantic models for request/response schemas.
+  - Proper error handling (404 if config not found, 400 on validation errors).
+  - Type hints everywhere.
+
+## Frontend
+
+Create a small React + TypeScript SPA:
+
+- Pages:
+  - Login/register page.
+  - Config list page.
+  - Config detail/edit page with tabs for:
+    - Zones
+    - Interfaces
+    - Policies
+    - Rules
+    - Masq/NAT
+- Each tab:
+  - Shows a table of existing entries.
+  - Has forms to create/edit/delete entries.
+- Generation UI:
+  - On the config detail page, add a “Generate Shorewall config” button that calls `/configs/{id}/generate`.
+  - Show the generated file contents in a modal dialog or separate view with tabs for zones/interfaces/policy/rules/masq.
+  - Add a button to download the ZIP (if you implement ZIP) or copy text.
+- Implementation details:
+  - Use React Router for navigation.
+  - API client:
+    - Centralized `api.ts` that wraps fetch/axios calls with the correct base URL and auth headers.
+  - Minimal styling with MUI or Tailwind; keep it functional, not pretty.
+
+## Project structure and tooling
+
+Provide:
+
+- A clear project layout, e.g.:
+
+  - backend/
+    - app/main.py
+    - app/models.py
+    - app/schemas.py
+    - app/api/
+    - app/services/
+    - app/shorewall_generator.py
+    - alembic/…
+  - frontend/
+    - src/App.tsx
+    - src/routes/…
+    - src/components/…
+    - src/api.ts
+  - docker-compose.yml
+  - README.md
+
+- Docker:
+  - `docker-compose.yml` to run:
+    - backend service
+    - frontend service
+    - postgres
+  - Provide Dockerfiles for backend and frontend.
+
+## What to output
+
+- All core backend files (FastAPI app, models, schemas, routers, shorewall generator).
+- All core frontend files (entry, routes, main pages, key components).
+- Database and migration setup.
+- Dockerfiles and docker-compose.yml.
+- A concise README with:
+  - How to start dev environment.
+  - How to create the first user.
+  - How to create a config and generate Shorewall files.
+
+Focus on correctness, a clean structure, and code that I can copy into a repo and run with minimal adjustments.