Tech Debt: Consolidate duplicated business logic between REST API and GraphQL

[filiperochalopes]

User story

As a developer, I want REST API and GraphQL endpoints to share the same business logic so new features, bug fixes, and maintenance only need to be implemented once.

Use case

As CIEL Lab evolves, many features become available through both the REST API and GraphQL. Today, similar functionality is implemented and maintained independently, increasing development effort and the risk of behavioral inconsistencies.

Requirements

• Review the current REST API and GraphQL capabilities and identify overlapping functionality.
• Document redundant endpoints, queries, mutations, and business workflows.
• Define a shared service layer responsible for business logic.
• Refactor GraphQL resolvers to delegate business logic to the shared service layer where applicable.
• Refactor REST endpoints to delegate business logic to the same shared service layer where applicable.
• Preserve existing API contracts unless an explicit breaking change is approved.
• Ensure authorization, validation, auditing, and error handling remain consistent across both interfaces.
• Identify functionality that should exist exclusively in one interface and document the rationale.
• Produce migration recommendations for remaining duplicated implementations.

Acceptance criteria

• A technical assessment identifies redundant functionality between the REST API and GraphQL layers.
• Shared business logic is clearly separated from transport-specific code.
• REST and GraphQL produce consistent behavior for equivalent operations.
• New functionality can be implemented once and exposed through both interfaces with minimal duplication.
• A migration plan is available for remaining duplicated components.

More details

Technical context

CIEL Lab currently exposes both REST API and GraphQL interfaces. While this provides flexibility for different clients, it also increases maintenance cost because equivalent operations may evolve independently.

The goal of this task is not to remove either interface, but to reduce duplicated implementation by introducing a common application/service layer responsible for business rules.

The review should identify:

• duplicated validation logic
• duplicated authorization logic
• duplicated data transformation
• duplicated persistence workflows
• inconsistent error handling
• inconsistent response behavior
• opportunities for shared abstractions

The expected outcome is a cleaner architecture where REST and GraphQL become thin transport layers over the same business services.

Reference interfaces:

• REST API: https://ciellab.filipelopes.med.br/api/v2/docs
• GraphQL: https://ciellab.filipelopes.med.br/graphql

[ocl-automation]

Automated Triage — 2026-08-05

Dimension	Score
Complexity	4
Scope	4
Clarity	2
Dependency	1
Risk	3

Decision: decision/human-review
Type: type/refactor
Signals: signal/large-scope, signal/needs-spec

Significant architectural work requiring design decisions about shared abstractions across multiple API layers. Requirements are cut off and lack specific acceptance criteria, making clarity low. Moderate risk since incorrect abstraction could break existing API contracts.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).

[filiperochalopes]

Only extract shared services when the same operation is exposed through both boundaries. The concept merge pattern is already sound: REST starts the operation, GraphQL reads the preview, history, and status, and the business rule lives in the service layer.