Skip to content

BUILDPLAN.md

Latest commit

 

History

History
121 lines (86 loc) · 5.75 KB

BUILDPLAN.md

File metadata and controls

121 lines (86 loc) · 5.75 KB

SafeGen — Build Plan

Step-by-step build order. Each phase is independently deployable and testable.

Phase 1: Core Backend ✅

Goal: Working Azure Function that calls Azure OpenAI and returns a response.

  • Azure Functions Python v2 project with blueprint pattern
  • core/openai_client.py — Azure OpenAI wrapper with GenerationResult
  • core/models.py — Pydantic v2 request/response models
  • functions/validate.py — POST /api/validate (LLM proxy)
  • 26 tests passing (models, openai_client, validate)

Deliverable: POST /api/validate accepts a prompt and returns an Azure OpenAI response.

Phase 2: RAG Pipeline ✅

Goal: Upload compliance documents, chunk, index in FAISS, retrieve relevant rules.

  • core/rag_pipeline.py — text extraction (PDF/DOCX/MD), chunking (500 tokens, 50 overlap), HF embeddings, FAISS index
  • core/blob_storage.py — Azure Blob Storage CRUD
  • functions/ingest_rules.py — POST /api/rules/ingest (file upload)
  • functions/list_rules.py — GET /api/rules (list with previews)
  • Sample rule documents in rules/ (GDPR, bias, PII)
  • 51 tests passing (cumulative)

Deliverable: Upload a PDF, chunks indexed in FAISS, query returns relevant rule passages.

Phase 3: Compliance Engine ✅

Goal: Multi-layer validation of LLM responses against compliance rules.

  • core/validators.py — PIIDetector (email, phone, SSN, credit card, IPv4), BiasChecker (gendered terms, ableist language, stereotypes), SafetyFilter (hate, violence, self-harm)
  • core/compliance_engine.py — orchestrates validators, computes score (1.0 base, -0.3 critical, -0.1 warning)
  • Smart exclusions: example.com emails, date-like SSNs, version-like IPs, educational context
  • Category filtering via RulesCategory enum
  • Updated functions/validate.py with compliance pipeline + audit logging
  • 120 tests passing (cumulative, including 40 validator tests + 27 engine tests)

Deliverable: POST /api/validate returns { response, compliance: { passed, score, flags, layers_run } }.

Phase 4: Metrics & Audit API ✅

Goal: Audit log retrieval and aggregated metrics for the dashboard.

  • core/audit_logger.py — dual-backend store (FileAuditStore for local, BlobAuditStore for Azure)
  • functions/audit.py — GET /api/audit (paginated, date/status filters)
  • functions/metrics.py — GET /api/metrics (totals, rates, flag breakdown, time series)
  • Single-pass O(n) aggregation for metrics
  • 150 tests passing (cumulative)

Deliverable: GET /api/metrics returns dashboard-ready JSON. GET /api/audit returns paginated logs.

Phase 5: React Dashboard ✅

Goal: Monitoring dashboard showing compliance health at a glance.

  • Vite + React 19 + TypeScript (strict mode) + Tailwind CSS v4
  • shadcn/ui components (button, card, badge, table, dialog, input, select, separator, skeleton, tooltip)
  • Typed API client with error handling (ApiError class)
  • useApi<T> generic data-fetching hook, useTheme dark mode toggle
  • DashboardPage — 4 KPI cards, TrendChart (Recharts AreaChart), FlagBreakdownChart (BarChart), ScoreGauge, 60s auto-refresh
  • AuditPage — date/status filters, paginated table, detail modal with flag list
  • RulesPage — drag-and-drop upload zone, rule card grid
  • Responsive layout: fixed sidebar (256px), mobile hamburger, light/dark mode
  • Vite dev proxy /api → localhost:7071
  • 41 frontend tests passing (vitest + testing-library)

Deliverable: Full working dashboard at localhost:5173 consuming all 5 backend API endpoints.

Phase 6: Docker + CI/CD ✅

Goal: Containerize and automate testing/builds.

  • backend/Dockerfile — Azure Functions Python v4 container with health check
  • frontend/Dockerfile — multi-stage (Node build + nginx serve) with SPA routing
  • frontend/nginx.conf — SPA fallback + /api/ proxy to backend + asset caching
  • docker-compose.yml — full stack: backend + frontend + Azurite (Blob emulator), health checks, env passthrough
  • .dockerignore files for root, backend, frontend
  • GitHub Actions CI — 7 parallel jobs: backend lint/test/build, frontend lint/test/build, Docker build

Deliverable: docker-compose up --build runs the full stack. CI validates every push/PR.

docker-compose up --build
# Backend:  http://localhost:7071
# Frontend: http://localhost:5173
# Azurite:  http://localhost:10000

Test Summary

Module Tests What's Covered
test_models.py 17 Pydantic validation, all model types
test_openai_client.py 7 Azure OpenAI wrapper, error handling
test_validate.py 13 /api/validate endpoint, compliance integration
test_rag_pipeline.py 16 Extract, chunk, embed, FAISS, semantic search
test_ingest_rules.py 8 /api/rules/ingest, file parsing
test_compliance_engine.py 27 Scoring, flag aggregation, category filtering
test_validators.py 40 PII/bias/safety detectors, edge cases
test_audit.py 10 /api/audit, pagination, filters
test_audit_logger.py 6 File + Blob store backends
test_metrics.py 6 /api/metrics, aggregation
Frontend (8 files) 41 Formatters, API client, components, pages
Total 191 Backend: 150 + Frontend: 41