chore: initial project setup with backend, frontend, CI/CD, and documentation

Add complete NexaFabric project structure including:
- FastAPI backend with SQLAlchemy models, JWT auth, RBAC, audit logging, and provider interfaces
- React + TypeScript frontend with Vite, Tailwind CSS, TanStack Query, and Zustand
- Docker Compose configuration for PostgreSQL, Redis, API, worker, frontend, and nginx
- GitHub Actions and GitLab CI workflows for testing, linting, building, and security scanning
- Environment

docs/api-examples.md

@@ -0,0 +1,24 @@
+# API Examples
+
+Login:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@nexafabric.local","password":"ChangeMe_UseEnvInstead"}'
+```
+
+List clusters:
+
+```bash
+curl http://localhost:8080/api/v1/clusters \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Generate firewall preview:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/firewall/preview/$POLICY_ID \
+  -H "Authorization: Bearer $TOKEN"
+```
+

docs/architecture.md

@@ -0,0 +1,20 @@
+# Architecture
+
+NexaFabric is split into five layers:
+
+1. Frontend: React application for daily network, IPAM, policy, and audit operations.
+2. API: FastAPI REST surface with OpenAPI docs, JWT auth, RBAC hooks, and validation.
+3. Domain services: provider registry, policy engine, firewall orchestrator, audit service, and job coordination.
+4. Persistence: PostgreSQL through SQLAlchemy models. Alembic is intended for production migrations.
+5. Workers: background execution for sync, compile, drift detection, IPAM scans, cleanup, and backup export.
+
+Provider interfaces are intentionally separated into `HypervisorProvider`, `InventoryProvider`, `NetworkProvider`, and `FirewallProvider`. The first implementation is Proxmox, but the API layer is not tied directly to Proxmox-specific code.
+
+Firewall orchestration follows this flow:
+
+1. Policy definition is compiled.
+2. Conflicts and broad access warnings are calculated.
+3. Provider-specific preview output is produced.
+4. Audit log records the preview.
+5. A later apply path must verify cluster write mode, acquire a lock, and write a second audit record.
+

docs/backup-restore.md

@@ -0,0 +1,18 @@
+# Backup And Restore
+
+Back up:
+
+- PostgreSQL database
+- Environment file and secret material
+- Reverse proxy configuration
+- Optional worker queue state
+
+Restore:
+
+1. Stop API and workers.
+2. Restore PostgreSQL.
+3. Restore `.env` and encryption keys.
+4. Start PostgreSQL and Redis.
+5. Start API and workers.
+6. Run health checks and verify audit log continuity.
+

docs/developer-guide.md

@@ -0,0 +1,23 @@
+# Developer Guide
+
+Backend:
+
+```bash
+cd backend
+pip install ".[dev]"
+pytest
+ruff check .
+uvicorn app.main:app --reload
+```
+
+Frontend:
+
+```bash
+cd frontend
+npm install
+npm run dev
+npm test
+```
+
+The API docs are served at `/api/docs`.
+

docs/firewall-orchestration.md

@@ -0,0 +1,16 @@
+# Firewall Orchestration
+
+NexaFabric must never overwrite productive firewall state without operator intent.
+
+Required lifecycle:
+
+1. Compile policy.
+2. Generate preview.
+3. Detect warnings and conflicts.
+4. Persist audit record.
+5. Require approval for apply.
+6. Acquire a cluster/node lock.
+7. Apply provider-specific rules.
+8. Detect drift after apply.
+9. Support rollback using previous compiled versions.
+

docs/installation.md

@@ -0,0 +1,25 @@
+# Installation
+
+## Docker Compose
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+Change every secret in `.env` before using NexaFabric outside a local lab.
+
+## Proxmox API Token
+
+Create a least-privilege Proxmox API token and start in read-only mode. NexaFabric can inventory clusters, nodes, VMs, LXCs, networks, and firewall state before any write workflows are enabled.
+
+Recommended initial scope:
+
+- Cluster inventory read
+- Node inventory read
+- VM and LXC config read
+- SDN and network read
+- Firewall read
+
+Enable write permissions only for a dedicated automation token after previews and approvals are working.
+

docs/ipam.md

@@ -0,0 +1,12 @@
+# IPAM Concept
+
+NexaFabric tracks subnets, gateway, DNS, DHCP state, and individual IP addresses. IP states are:
+
+- free
+- reserved
+- assigned
+- deprecated
+- conflict
+
+The import workflow should scan existing VM and LXC network configuration, reserve discovered addresses, and flag duplicates as conflicts.
+

docs/provider-concept.md

@@ -0,0 +1,11 @@
+# Provider Concept
+
+Providers implement these interfaces:
+
+- `HypervisorProvider`
+- `InventoryProvider`
+- `NetworkProvider`
+- `FirewallProvider`
+
+The Proxmox provider is the first implementation. Future providers can be registered without changing API route code.
+

docs/rbac.md

@@ -0,0 +1,13 @@
+# RBAC Concept
+
+Built-in roles:
+
+- Super Admin
+- Network Admin
+- Security Admin
+- Tenant Admin
+- Auditor
+- Read Only User
+
+Permissions are stored as strings and can use wildcard entries. Tenant and project scoping should be enforced in query services as the implementation matures.
+

docs/security.md

@@ -0,0 +1,12 @@
+# Security Concept
+
+- Passwords use Argon2id through Passlib.
+- JWT access tokens are short-lived; refresh token rotation is part of the auth roadmap.
+- API tokens are represented as references in the current scaffold and must be encrypted before production use.
+- RBAC is role and permission based.
+- Firewall changes require preview, validation, locking, and audit records.
+- Proxmox write-enabled mode is explicit per cluster.
+- No dangerous default password should be used in production.
+- CORS origins are configured through environment settings.
+- SQL queries use SQLAlchemy ORM constructs.
+

docs/troubleshooting.md

@@ -0,0 +1,19 @@
+# Troubleshooting
+
+## API Cannot Reach Proxmox
+
+- Verify Proxmox URL and TLS settings.
+- Check token format and least-privilege role assignment.
+- Test routing from the API container.
+
+## Login Fails
+
+- Confirm demo seed data was created.
+- Verify database connectivity.
+- Reset the local admin password through a controlled maintenance task.
+
+## Firewall Preview Is Empty
+
+- Confirm at least one enabled policy exists.
+- Check policy definition source, destination, service, action, and direction.
+

docs/upgrade.md

@@ -0,0 +1,10 @@
+# Upgrade Guide
+
+1. Read release notes.
+2. Back up PostgreSQL and secrets.
+3. Pull the new version.
+4. Run database migrations.
+5. Restart API, workers, frontend, and proxy.
+6. Run health checks.
+7. Generate a firewall preview before any apply workflow.
+