gremiumhub/api/CLAUDE.md

API - AI Context

Overview

OpenAPI 3.0.3 specification serves as the single source of truth for all API contracts. Both frontend and backend clients are auto-generated from this spec.

---

API Endpoints

# Forms
GET/POST   /application-forms
GET/PUT/DELETE /application-forms/{id}
POST       /application-forms/{id}/submit

# Templates
GET/POST   /application-form-templates
GET/PUT/DELETE /application-form-templates/{id}

# Versions
GET        /application-forms/{id}/versions
GET        /application-forms/{id}/versions/{n}
POST       /application-forms/{id}/versions/{n}/restore
GET        /application-forms/{id}/versions/{n}/pdf

# Comments
GET        /application-forms/{id}/comments
POST       /application-forms/{id}/form-elements/{elementId}/comments
PUT/DELETE /comments/{id}

# Notifications
GET        /notifications?organizationId=
GET        /notifications/unread/count?userId=&organizationId=  (public)
PUT        /notifications/{id}/mark-read
PUT        /notifications/mark-all-read
DELETE     /notifications/clear-all

---

Key Files

File	Purpose
legalconsenthub.yml	OpenAPI 3.0.3 specification (source of truth)

---

API-First Workflow

1. Modify OpenAPI spec (api/legalconsenthub.yml)

   • Add/update endpoints, request/response schemas
   • Follow OpenAPI 3.0.3 standards
   • Document all parameters and responses

2. Generate clients

   # Frontend TypeScript client
   cd legalconsenthub && pnpm run api:generate
   
   # Backend Kotlin server stubs
   cd legalconsenthub-backend && ./gradlew generate_legalconsenthub_server
   

3. Implement backend logic

   • Server stubs are generated, implement the actual business logic
   • Use mapper classes for DTO ↔ Entity conversions

4. Use frontend client

   • Auto-generated TypeScript client available in frontend
   • Type-safe API calls with full IDE support

---

Rules for AI

1. Never skip OpenAPI spec - All API changes must start here
2. Validate spec - Ensure OpenAPI 3.0.3 compliance before generating clients
3. Document everything - All endpoints, parameters, responses, and schemas must be documented
4. Breaking changes - Consider versioning strategy for breaking API changes
5. Regenerate clients - Always regenerate both frontend and backend clients after spec changes

Schema Design Guidelines

• Use $ref for reusable components
• Define clear request/response schemas
• Include validation constraints (min/max, pattern, required)
• Use enums for fixed value sets
• Document all fields with descriptions