Developer reference: Framework setup (/setup/frameworks)

This document covers the framework definition catalogue, org framework projects (OrgFramework), and the primary HTTP API under /api/frameworks. It summarizes the FrameworkList page at /setup/frameworks; it does not exhaust every control/evidence/risk sub-endpoint (see framework.routes.ts for the full tree).

Repository layout

• Web client: gaicc-app/Clients
• API server: gaicc-app/Servers

---

Routing and pages

Item	Location
Framework setup UI	gaicc-app/Clients/src/presentation/pages/setup/FrameworkList.tsx — route /setup/frameworks in App.tsx
Legacy detail route	FrameworkDetail.tsx redirects to /setup/frameworks (single-page UX)
Create / edit modal	gaicc-app/Clients/src/presentation/components/CreateFrameworkModal.tsx
Tab navigation	FrameworkTabNav.tsx; tab from ?tab= — valid: dashboard | risks | models | controls | settings (FrameworkList.tsx)

---

Client data layer

Concern	Location
Query keys	gaicc-app/Clients/src/application/queries/framework.queries.ts — frameworkKeys (available, projects, project(id), controls(...))
Catalogue	useAvailableFrameworks → GET /api/frameworks
Projects list	useFrameworkProjects → GET /api/frameworks/projects
Create project	useCreateFrameworkProject → POST /api/frameworks/projects; invalidates frameworkKeys.projects, available, qk.dashboard, plan usage
Repository	gaicc-app/Clients/src/infrastructure/repositories/framework.repository.ts

DTOs — gaicc-app/Clients/src/domain/types/framework.types.ts — CreateFrameworkProjectDto, UpdateFrameworkProjectDto, etc.

---

API surface (app.use("/api", frameworkRoutes))

All routes in framework.routes.ts run authenticateJWT, attachOrganizationId, enforceMutationBillingCompliance unless noted below. Static paths are registered before /:id routes.

Method	Path	Notes
GET	/frameworks	Global catalogue of active Framework definitions; each row includes isActivated if the org already linked that definition via OrgFrameworkRegulation (framework.service getAvailableFrameworks)
GET	/frameworks/projects	List OrgFramework projects for the tenant
POST	/frameworks/projects	enforcePlanLimit("frameworks") — create project (Admin or Editor only in controller)
GET	/frameworks/projects/:id	Single project
PUT	/frameworks/projects/:id	Update project (Admin or Editor)
DELETE	/frameworks/projects/:id	Soft-delete project
GET	/frameworks/projects/:id/stats	Aggregated stats
GET	/frameworks/projects/:id/controls	Optional query useCaseProjectId
PUT	/frameworks/projects/:id/controls/:orgControlId/status	Status-only patch
GET/PUT	.../controls/:orgControlId	Detail + full update
Risks / evidence	Additional GET/POST/DELETE routes under .../controls/:orgControlId/... and .../projects/:id/risks — many gated with enforceSubscription
Regulations	POST/DELETE .../projects/:id/regulations	Add/remove linked framework definitions on a project

Controller — gaicc-app/Servers/src/controllers/framework.controller.ts

• Uses Zod CreateProjectSchema / UpdateProjectSchema; errors often return { error: ... } (flatten or string) — not always { message } like some auth routes.
• createFrameworkProject / updateFrameworkProject: 403 Insufficient permissions if role is not Admin or Editor.

Service — gaicc-app/Servers/src/services/framework.service.ts

• getAvailableFrameworks: loads active Framework rows; marks isActivated when OrgFrameworkRegulation exists for this org.
• createFrameworkProject: validates regulation UUIDs, creates OrgFramework, members, links regulations, instantiates control trees (e.g. ISO 27001 / ISO 42001 branches by fw.slug), large transactions (comment notes 60s timeout in code).

---

Testing notes (TestSprite / external)

• Happy path: GET /api/frameworks + POST /api/frameworks/projects with a valid applicableRegulations array and Admin/Editor user.
• GET /api/frameworks/projects returns [] until a project exists — matches FrameworkList empty state.
• Configure scope in the TestSprite web portal; use this file and framework.routes.ts for exhaustive route lists.