Add NixOS VM integration tests and update CI/CD pipeline configuration. Introduce checks for backend integration, full-stack, performance, and security tests using native NixOS services. Remove legacy GitHub Actions workflow and replace with Gitea Actions runner configuration. Update README and quickstart guide to reflect new development environment setup and testing commands.

specs/001-reference-board-viewer/tech-research.md

@@ -654,7 +654,126 @@ The recommended stack (Svelte + Konva.js + FastAPI + PostgreSQL) provides the op
 - ✅ Developer experience (modern tooling, fast feedback)
 - ✅ Maintainability (clear architecture, good docs)
 - ✅ Scalability (can grow from MVP to production)
-- ✅ Leverages existing setup (Python in shell.nix)
+- ✅ Leverages existing setup (Python dependencies managed by Nix)
 
 This stack is production-ready, future-proof, and fully aligned with your Nix deployment requirement.
 
+---
+
+## CI/CD Architecture
+
+### Decision: NixOS VM Tests (No Docker)
+
+**Chosen Approach:** NixOS VM integration tests using `pkgs.nixosTest`
+
+**Why NixOS VMs over Docker:**
+
+| Aspect | Docker Compose | NixOS VMs (Chosen) |
+|--------|----------------|-------------------|
+| Isolation | Container (shared kernel) | Full VM (separate kernel) |
+| Reproducibility | Image tags can drift | `flake.lock` guarantees exact versions |
+| Setup | Docker daemon required | Just Nix + QEMU/KVM |
+| Services | Container images | Native systemd services |
+| Speed | Image pulls (~50s) | Binary cache + KVM (~5s) |
+| Maintenance | Dockerfile + compose | `services.X.enable = true` |
+| Cleanup | Manual or scripted | Automatic (VM destroyed) |
+
+**Key Benefits:**
+1. **Complete isolation** - Full VM per test, cannot affect host
+2. **Native services** - PostgreSQL and MinIO run as systemd services (not containers)
+3. **Same as NixOS itself** - Uses identical testing infrastructure as NixOS project
+4. **Parallel execution** - 4 VMs run simultaneously (~30s total)
+5. **Zero Docker dependency** - No Docker daemon, no image registry
+6. **Perfect reproducibility** - flake.lock guarantees bit-identical environments
+
+**Implementation:**
+
+```nix
+# nixos/tests.nix
+backend-integration = pkgs.nixosTest {
+  nodes.machine = {
+    services.postgresql.enable = true;  # Native systemd service
+    services.minio.enable = true;       # Native systemd service
+  };
+  
+  testScript = ''
+    machine.wait_for_unit("postgresql.service")
+    machine.wait_for_unit("minio.service")
+    machine.succeed("pytest backend/tests/")
+  '';
+};
+```
+
+**CI Workflow:**
+- 4 parallel NixOS VMs (backend-integration, full-stack, performance, security)
+- Linting and unit tests (no VM needed)
+- Build verification
+- Total time: ~30 seconds with caching
+- **Attic binary cache**: Shares build artifacts across CI runs for faster builds
+
+**Alternative Considered:** Docker Compose
+- ❌ Rejected due to: Docker daemon dependency, less isolation, image maintenance overhead
+- Docker would add complexity without benefits (NixOS services are cleaner)
+
+### Development Environment
+
+**Decision:** Single `flake.nix` as source of truth (no shell.nix)
+
+**Structure:**
+```nix
+flake.nix
+├─ devShells.default (Python, Node.js, PostgreSQL client, etc.)
+├─ packages.backend (production build)
+├─ packages.frontend (production build)
+└─ checks.* (NixOS VM tests)
+```
+
+**Commands:**
+```bash
+nix develop              # Enter dev shell
+nix flake check          # Run all VM tests
+nix build .#backend      # Build backend package
+```
+
+**Why flake-only:**
+- Single source of truth (no shell.nix duplication)
+- Flake lock guarantees reproducibility
+- Same environment in dev, CI, and production
+- Modern Nix best practice
+
+### Test Organization
+
+**Unit tests:** Fast, no external services (pytest, Vitest)
+**Integration tests:** NixOS VMs with PostgreSQL + MinIO
+**E2E tests:** Full-stack VM with running API
+**Performance tests:** Dedicated VM for benchmarks
+**Security tests:** Isolated VM for security validation
+
+All integration tests use **native NixOS services**, not Docker containers.
+
+### Binary Cache (Attic)
+
+**Setup:** Self-hosted Attic cache server at `http://127.0.0.1:2343`
+
+**Purpose:** Share Nix build artifacts across CI runs to significantly speed up builds.
+
+**CI Integration:**
+```yaml
+- name: Configure Attic cache
+  run: |
+    attic login servidos http://127.0.0.1:2343 ${{ secrets.ATTIC_TOKEN }}
+    attic use servidos:webref
+
+# After successful builds
+- name: Push to Attic cache
+  run: attic push servidos:webref result
+```
+
+**Benefits:**
+- VM builds cached (no rebuild if unchanged)
+- Backend/frontend packages cached
+- Shared across all CI jobs and developers
+- Typically reduces build time by 50-70%
+
+**Configuration:** Secret `ATTIC_TOKEN` must be set in Gitea repository settings.
+