Skip to main content

GraphQL Architecture

Schema-first. Schema files in src/main/resources/graphql/*.graphqls.

Layer structure​

  • Schema — queries.graphqls, mutations.graphqls, plus per-entity files (e.g., users.graphqls)
  • Controllers — in web/ subpackages; annotated @Controller; class-level @PreAuthorize("isAuthenticated()"); @QueryMapping / @MutationMapping
  • DTOs — in web/dto/; match GraphQL types exactly
  • Mappers — in web/; extend BaseMapper<Entity, EntityDto, EntityInput>; MapStruct; @AfterMapping for bidirectional references
  • Services — in feature root package (e.g., UserService.java); receive currentUserId as method parameter
  • Repositories — extend BaseRepository or JpaRepository

Constraints​

  • Do NOT inject CurrentUserContext into services — resolve currentUserId in the controller
  • For workspace subclass fields, query the subclass in JPQL: SELECT w FROM OrgWorkspace w WHERE w.orgId = :orgId
  • Class-level @PreAuthorize("isAuthenticated()") on all controllers; method-level annotations narrow further
  • Read endpoints: use membership checks (hasUserAnyOrgRole, hasUserAnyWorkspaceRole)
  • Write endpoints: use permission matrix checks (hasUserSystemPermission, hasUserApplicationPermission)