-

CLAUDE.md

@@ -251,6 +251,7 @@ LOG_FORMAT=json
 - **Authentication**: `/api/login`, `/api/verify`, `/api/renew`
 - **Applications**: `/api/applications` (CRUD operations)
 - **Tokens**: `/api/applications/{id}/tokens` (Static token management)
+- **Audit**: `/api/audit/events`, `/api/audit/events/:id`, `/api/audit/stats` (Audit log management)
 - **Metrics**: `:9090/metrics` (Prometheus format, if enabled)
 
 ### Permission System
@@ -272,7 +273,11 @@ Example: `repo` permission includes `repo.read` and `repo.write`.
 - `available_permissions` - Permission catalog
 - `granted_permissions` - Token-permission relationships
 - `user_sessions` - User session tracking with JWT
-- `audit_events` - Comprehensive audit logging
+- `audit_events` - Comprehensive audit logging with fields:
+  - `id`, `type`, `severity`, `status`, `timestamp`
+  - `actor_id`, `actor_type`, `actor_ip`, `user_agent`
+  - `resource_id`, `resource_type`, `action`, `description`
+  - `details` (JSON), `request_id`, `session_id`
 
 ### Migration System
 - Auto-runs on startup
@@ -298,6 +303,7 @@ Example: `repo` permission includes `repo.read` and `repo.write`.
 - **Axios** for API communication with interceptors
 - **React Router 7+** for navigation
 - **Component Structure**: Organized by feature (Applications, Tokens, Users, Audit)
+- **Audit Integration**: Real-time audit log viewing with filtering, statistics, and timeline views
 
 ### Security Patterns
 - **HMAC Token Signing**: All tokens cryptographically signed
@@ -307,6 +313,16 @@ Example: `repo` permission includes `repo.read` and `repo.write`.
 - **Audit Logging**: All operations logged with user attribution
 - **Input Validation**: Comprehensive validation at all layers
 
+### Audit System Architecture
+- **Handler**: `internal/handlers/audit.go` - HTTP endpoints for audit data
+- **Logger**: `internal/audit/audit.go` - Core audit logging functionality
+- **Repository**: `internal/repository/postgres/audit_repository.go` - Data persistence
+- **Frontend**: `kms-frontend/src/components/Audit.tsx` - Real-time audit viewing
+- **API Service**: `kms-frontend/src/services/apiService.ts` - Frontend-backend integration
+- **Event Types**: Hierarchical (e.g., `auth.login`, `app.created`, `token.validated`)
+- **Filtering**: Support for date ranges, event types, statuses, users, resource types
+- **Statistics**: Aggregated metrics by type, severity, status, and time
+
 ## Development Notes
 
 ### Critical Information
@@ -332,6 +348,13 @@ Example: `repo` permission includes `repo.read` and `repo.write`.
 5. Use E2E tests to verify end-to-end functionality
 6. Frontend dev server connects to containerized backend
 
+### Build & Deployment Notes
+- **Cache Issues**: When code changes don't appear, use `podman-compose build --no-cache`
+- **Route Registration**: New API routes require full rebuild to appear in Gin debug logs
+- **Error Handlers**: Use `HandleInternalError`, `HandleValidationError`, `HandleAuthenticationError`
+- **API Integration**: Frontend components should use real API calls, not mock data
+- **Field Mapping**: Ensure frontend matches backend field names (e.g., `actor_id` vs `user_id`)
+
 ### Security Considerations
 - Never commit secrets to repository
 - All tokens use HMAC signing with secure keys