Compliance Tracker Client (React + Vite)

Frontend client for the Compliance Tracker platform. It orchestrates compliance audits, gap tracking, document ingestion, and AI-assisted guidance. The app connects to the companion Compliance Tracker API to authenticate users, manage audit sessions, attach documents, monitor remediation gaps, and chat with an AI auditor that ingests your evidence.

This README focuses on the client. For the backend reference and API contract, see “Compliance Tracker API” summary below.

Added Value

• Secure authentication with automatic token refresh and protected routes.
• Dashboard centralizes audit sessions, reports, compliance gaps, and quick actions.
• Document ingestion workflows tie evidence to audits with metadata and status.
• Streaming chat guidance inside each audit session for generating findings and reports.
• Typed React + Vite codebase with modular feature slices for rapid iteration.

Technology Stack

• React 19 + TypeScript, Vite 6
• Tailwind CSS v4, shadcn/ui components, lucide-react icons
• React Router DOM 7 for routing
• Zustand for state, axios + fetch for API
• ESLint 9 with modern TypeScript configuration

Prerequisites

• Node.js 18+ (Node 20+ recommended)
• npm 9+ (or compatible package manager)
• Running Compliance Tracker backend reachable from the browser

Environment

Create a .env file in the project root (or set env at runtime) to point the client at your API. Only one variable is required:

VITE_API_URL=http://localhost:8000

Notes:

• Default fallback is http://localhost:8000 when VITE_API_URL is not set (see src/modules/api/http.ts and src/modules/chat/services/core/chatStreamService.ts).
• Ensure backend CORS allows the Vite dev origin (e.g., http://localhost:5173).
• Tokens are stored in localStorage; configure backend token lifetimes and refresh endpoints accordingly.

How To Run

Install dependencies:

npm install

Start the dev server (Vite):

npm run dev

Open the printed URL (usually http://localhost:5173).

Build and preview the production bundle:

npm run build
npm run preview

Lint:

npm run lint

Usage

• Welcome page invites users to sign up or log in before accessing protected workflows.
• Login and signup forms call the /v1/auth/* endpoints and persist tokens for subsequent requests.
• Dashboard (/dashboard) summarizes audit reports, active sessions, and open compliance gaps with quick-start cards.
• Audit sessions (/audit-sessions/*) provide creation forms, detail views, document linking, and history retrieval for each engagement.
• Documents section (/documents/*) lists ingested PDFs, uploads new evidence with metadata, and surfaces tags/domains.
• Compliance gaps (/compliance-gaps/*) let you create, edit, and review remediation items tied to standards.
• Audit reports (/audit-reports/*) build, edit, and view reports fed by chat findings and session data.
• Chat workspace (/audit-sessions/:sessionId/chat/:chatId) streams AI responses, buffers tokens for smooth rendering, and records conversation IDs from response headers.
• Report creation via chat (/audit-sessions/:sessionId/create-report) guides assembling structured findings from streamed answers.
• Tip: Upload and associate relevant documents with an audit session before starting a chat for richer guidance.

Project Structure

.
├── index.html
├── vite.config.ts                 # Vite + React + Tailwind plugin, alias '@'
├── src/
│   ├── main.tsx                   # App bootstrap and router mounting
│   ├── App.tsx                    # Route map, guards, and shared layouts
│   ├── index.css                  # Tailwind v4 setup + theme tokens
│   ├── components/                # Layouts, dashboard widgets, shared UI
│   ├── pages/                     # Dashboard and welcome/marketing pages
│   ├── modules/                   # Feature slices grouped by domain
│   │   ├── api/                   # Axios instance + interceptors
│   │   ├── auth/                  # Auth components, services, Zustand store
│   │   ├── audit/                 # Audit session UI, hooks, and services
│   │   ├── audit-reports/         # Report builder components and hooks
│   │   ├── chat/                  # Chat UI, streaming service, local store
│   │   ├── compliance-gaps/       # Gap CRUD forms, detail views, hooks
│   │   ├── documents/             # Document ingestion list/upload flows
│   │   └── iso-control/           # ISO control mapping utilities and store
│   ├── lib/                       # Reusable utilities and domain helpers
│   └── assets/                    # Static assets referenced in UI
├── public/                        # Static assets served directly
├── package.json                   # Scripts and dependencies
├── tsconfig*.json                 # TypeScript project references
├── eslint.config.js               # ESLint configuration
└── README.md

How It Works (Client)

• Authentication is handled by useAuthStore (Zustand) calling authService; axios interceptors attach Bearer tokens and retry once with refresh tokens on 401 responses.
• Feature services in src/modules/*/services wrap REST endpoints (/v1/audit-sessions, /v1/ingestions, /v1/compliance-gaps, etc.) and normalize server payloads before they reach components.
• Hooks provide UI-friendly selectors for lists, filters, and mutations while keeping state in colocated stores.
• Chat streaming (src/modules/chat/services/core/chatStreamService.ts) posts to /v1/query-stream, handles token refresh, emits incremental tokens to the UI, and records conversation metadata from response headers.
• Layout components coordinate navigation, shell UI, and loading states so feature modules focus on domain logic.

Backend Reference (Compliance Tracker API)

This client targets the companion Compliance Tracker API. Ensure it is running and reachable at VITE_API_URL.

Key endpoints expected by the client:

• POST /v1/auth/login, POST /v1/auth/signup, POST /v1/auth/refresh, POST /v1/auth/logout
• Document ingestion: GET/POST /v1/ingestions, /v1/ingestions/upload, /v1/ingestions/compliance-domain/{domain}
• Audit sessions: GET/POST /v1/audit-sessions, /v1/ingestions/audit-sessions/{session_id}, /v1/history/audit-sessions/{session_id}
• Chat and reports: POST /v1/query, POST /v1/query-stream, GET /v1/history/{conversation_id}
• Compliance gaps & ISO controls: /v1/compliance-gaps, /v1/iso-controls, /v1/compliance-domains

Consult the backend repository for authentication setup, schemas, and deployment guidance.

Developing Further

• Stream tokens directly into the chat bubble for real-time typing effects instead of buffering the full response.
• Enhance document uploads with drag-and-drop, progress indicators, and ingestion status history.
• Display cited document passages alongside AI answers to improve traceability.
• Add role-based access control in the UI to distinguish auditors, reviewers, and administrators.
• Cache key resources (sessions, gaps, documents) with background refetch for offline resilience.
• Surface analytics dashboards summarizing compliance gap status, remediation SLAs, and audit coverage.

Troubleshooting

• Repeated 401 responses indicate expired tokens—verify refresh endpoints and CORS headers allow credentialed requests.
• If chat streaming stalls, confirm the backend streams text/plain chunks and intermediate proxies are not buffering responses.
• Upload failures often stem from backend size limits or missing multipart handlers; inspect network responses for error details.
• Refreshing nested routes that return 404s requires configuring your host to serve index.html for unknown paths (SPA fallback).

Scripts

• npm run dev: start Vite dev server.
• npm run build: type-check and build for production.
• npm run preview: preview the production build locally.
• npm run lint: run ESLint with the project configuration.