proxmox-selfservice/README.md

You are helping implement an internal web application called Support Provisioning Portal.

Your task is to bootstrap the project based on the local README.md in this repository and then implement the first vertical slice with strong engineering discipline.

Product context

The application is an internal self-service portal for support staff. It provisions standardized VMs on Proxmox VE through a backend service. Users must never interact with Proxmox directly.

Typical resources:

• turnkey PBX/test appliances
• Windows support clients
• Linux utility VMs

The system must enforce:

• template-based provisioning only
• policy-controlled resource limits
• audit logging
• lifecycle actions
• TTL / expiration support

Technical direction

Use this stack unless the repository already contains an equivalent decision:

• Monorepo with pnpm
• Next.js + TypeScript for apps/web
• Node.js + TypeScript for apps/api
• Fastify preferred for the API
• PostgreSQL + Prisma
• Tailwind CSS for the web UI
• Zod for request/response validation

Constraints

• Do not overengineer.
• Prefer a clean vertical slice over broad scaffolding.
• Keep Proxmox integration behind a dedicated adapter/module.
• Use clear domain names and explicit types.
• Avoid magic strings.
• Add TODOs only when truly necessary.
• Document all non-obvious decisions in code comments or small docs.
• Make the codebase easy to extend toward RBAC, SSO, and multi-cluster support later.

Initial implementation goals

Implement a usable first slice with the following:

1. Monorepo structure

   • apps/web
   • apps/api
   • packages/types
   • packages/proxmox-client
   • prisma

2. Database schema with at least:

   • users
   • templates
   • deployments
   • audit_logs

3. Backend API endpoints

   • GET /api/templates
   • GET /api/deployments
   • GET /api/deployments/:id
   • POST /api/deployments
   • POST /api/deployments/:id/start
   • POST /api/deployments/:id/stop
   • DELETE /api/deployments/:id

4. Proxmox adapter

   • token auth support
   • stubbed or mockable implementation if no live environment is available
   • methods for clone/start/stop/delete/getStatus
   • clear interface separation between domain service and transport

5. Web UI

   • dashboard page listing deployments
   • templates page
   • create deployment form
   • deployment detail view
   • simple status badges and action buttons

6. Seed data

   • at least 3 sample templates

7. Audit logging

   • every mutating action must write an audit log row

8. Developer experience

   • .env.example
   • scripts for dev/build/lint
   • basic README sections updated if needed

Working style

Proceed in small, reviewable steps:

1. inspect repository
2. propose concrete file plan
3. implement foundation
4. implement backend slice
5. implement frontend slice
6. verify types/build consistency
7. summarize what was created and what remains

Output requirements

• Start by reading the local README.md and align implementation with it.
• Show the file/folder plan before making broad changes.
• Then create the project incrementally.
• When assumptions are required, state them briefly and choose the most pragmatic path.
• Favor production-style code structure over tutorial-style code.
• Where live Proxmox access is unavailable, create a mock adapter that can later be replaced without touching domain logic.

Quality bar

• TypeScript strict mode
• input validation at API boundaries
• no secrets committed
• minimal but coherent UI
• compile-ready code where possible
• no dead code
• no fake features presented as complete

Begin by inspecting the repository and proposing the exact bootstrap structure to create.