shorefront/instructions.md

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
  • 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.