Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-backend-graphql-apollo

tpl-backend-graphql-apollo

Verified

Template do pack (backend/05-graphql-apollo.md). Orienta o agente em APIs, servicos e arquitetura backend alinhado a esse contexto.

PROJECT: GraphQL API (Apollo Server + Prisma)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: backend/05-graphql-apollo.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

TechnologyVersionPurpose
Node.js22.xRuntime
TypeScript5.4+Language
Apollo Server4.xGraphQL server
GraphQL16.xQuery language
Prisma5.xORM + migrations
PostgreSQL16Primary database
DataLoader2.xBatching + caching (N+1 prevention)
Zod3.xInput validation
jsonwebtoken9.xJWT tokens
Vitest1.xUnit tests
graphql-ws5.xWebSocket-based subscriptions

PROJECT STRUCTURE

src/
├── schema/
│   ├── typeDefs/
│   │   ├── user.graphql      # SDL type definitions
│   │   ├── post.graphql
│   │   └── auth.graphql
│   └── index.ts              # mergeTypeDefs + makeExecutableSchema
├── resolvers/
│   ├── user/
│   │   ├── queries.ts        # User queries
│   │   ├── mutations.ts      # User mutations
│   │   └── fields.ts         # Field resolvers (e.g., User.posts)
│   ├── auth/
│   │   ├── mutations.ts
│   │   └── subscriptions.ts
│   └── index.ts              # mergeResolvers
├── dataloaders/
│   ├── userLoader.ts         # DataLoader for batching user queries
│   ├── postLoader.ts
│   └── index.ts              # Loader factory per request
├── services/
│   └── users/
│       └── users.service.ts
├── context/
│   └── index.ts              # Context builder (auth + loaders + prisma)
├── middleware/
│   └── auth.ts               # Token extraction + user injection
├── lib/
│   └── prisma.ts             # Prisma client singleton
├── server.ts                 # Apollo Server + Express setup
└── generated/
    └── graphql.ts            # codegen output (never edit manually)
prisma/
├── schema.prisma
└── migrations/
codegen.yml

ARCHITECTURE RULES

  • Schema-first development: always write .graphql SDL files first, then resolvers
  • Resolvers are thin: validate inputs with Zod, call service, return result
  • Services contain all business logic — resolvers never query Prisma directly
  • DataLoaders are created per request (in context factory) — never shared across requests
  • Authentication is checked in context builder for protected operations; resolvers check context.user
  • Never return internal error details in GraphQL errors — use user-friendly messages
  • codegen.yml regenerated whenever schema changes: npx graphql-codegen

Schema-First vs Code-First Decision

Use Schema-First (SDL)Use Code-First
Team has frontend + mobile consumersSolo backend dev, schema evolves fast
Contract-first with external teamsTypeScript-centric team, schema from types
This project's choice ✅Schema-as-code preference

RESOLVER RULES

// src/resolvers/user/queries.ts
import { z } from 'zod'
import { QueryResolvers } from '../../generated/graphql'
import { UserService } from '../../services/users/users.service'
import { GraphQLError } from 'graphql'

const paginationSchema = z.object({
  first: z.number().int().min(1).max(100).default(20),
  after: z.string().optional(),
})

export const userQueries: QueryResolvers = {
  me: async (_parent, _args, context) => {
    if (!context.user) {
      throw new GraphQLError('Not authenticated', {
        extensions: { code: 'UNAUTHENTICATED' },
      })
    }
    return context.services.users.getById(context.user.id)
  },

  users: async (_parent, args, context) => {
    if (!context.user?.isAdmin) {
      throw new GraphQLError('Not authorized', {
        extensions: { code: 'FORBIDDEN' },
      })
    }
    const { first, after } = paginationSchema.parse(args)
    return context.services.users.list({ first, after })
  },
}

Field Resolvers

// src/resolvers/user/fields.ts — NEVER query DB here, use DataLoader
import { UserResolvers } from '../../generated/graphql'

export const UserFieldResolvers: UserResolvers = {
  posts: async (parent, _args, context) => {
    // DataLoader batches all `posts` field calls in a single query
    return context.loaders.postsByUserId.load(parent.id)
  },
  // total is computed, not stored
  postCount: async (parent, _args, context) => {
    const posts = await context.loaders.postsByUserId.load(parent.id)
    return posts.length
  },
}

DATALOADER PATTERN

DataLoaders MUST be created fresh per request to avoid cross-request cache pollution.

// src/dataloaders/userLoader.ts
import DataLoader from 'dataloader'
import { prisma } from '../lib/prisma'
import type { User } from '@prisma/client'

export function createUserLoader() {
  return new DataLoader<string, User | null>(
    async (ids: readonly string[]) => {
      const users = await prisma.user.findMany({
        where: { id: { in: ids as string[] } },
      })
      // Result MUST be in same order as input ids
      const userMap = new Map(users.map(u => [u.id, u]))
      return ids.map(id => userMap.get(id) ?? null)
    },
    { cache: true } // cache within a single request context
  )
}

// src/dataloaders/index.ts
export function createLoaders() {
  return {
    userById: createUserLoader(),
    postsByUserId: createPostsByUserIdLoader(),
  }
}
// src/context/index.ts
import { Request } from 'express'
import { prisma } from '../lib/prisma'
import { createLoaders } from '../dataloaders'
import { verifyToken } from '../middleware/auth'
import { UserService } from '../services/users/users.service'

export async function buildContext({ req }: { req: Request }) {
  const user = verifyToken(req.headers.authorization)  // null if unauthenticated
  return {
    user,
    prisma,
    loaders: createLoaders(),  // new instances per request
    services: {
      users: new UserService(prisma),
    },
  }
}

export type GraphQLContext = Awaited<ReturnType<typeof buildContext>>

SUBSCRIPTION EXAMPLE

// src/resolvers/auth/subscriptions.ts
import { SubscriptionResolvers } from '../../generated/graphql'
import { PubSub } from 'graphql-subscriptions'

export const pubsub = new PubSub()
export const USER_JOINED = 'USER_JOINED'

export const authSubscriptions: SubscriptionResolvers = {
  userJoined: {
    subscribe: (_parent, _args, context) => {
      if (!context.user?.isAdmin) throw new Error('Forbidden')
      return pubsub.asyncIterator([USER_JOINED])
    },
    resolve: (payload) => payload.userJoined,
  },
}

ROUTING TABLE

TriggerOperationFieldAuthResolver
Get selfQuerymeBeareruserQueries.me
List usersQueryusers(first, after)Bearer + AdminuserQueries.users
Get userQueryuser(id)Bearer + AdminuserQueries.user
RegisterMutationregister(input)PublicauthMutations.register
LoginMutationlogin(input)PublicauthMutations.login
RefreshMutationrefreshToken(token)PublicauthMutations.refresh
Update profileMutationupdateMe(input)BeareruserMutations.updateMe
Delete accountMutationdeleteAccountBeareruserMutations.deleteAccount
New user joinedSubscriptionuserJoinedBearer + AdminauthSubscriptions.userJoined

QUALITY GATES

Before opening a PR, verify ALL of the following:

  • npx tsc --noEmit passes — no type errors in resolvers or context
  • npx graphql-codegen run — generated types match current schema
  • vitest run passes with zero failures
  • No resolver queries Prisma directly — goes through services
  • DataLoaders used for all field resolvers that load relations
  • New queries/mutations have authenticated + unauthenticated test cases
  • extensions.code set on all GraphQLError throws (UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT)
  • Subscription handlers check authentication
  • Input fields validated with Zod before passing to services
  • No any in resolver return types — use generated types from codegen

FORBIDDEN

  • NEVER query Prisma inside resolvers — only call services or use DataLoaders
  • NEVER share DataLoader instances across requests — always create per request in context
  • NEVER use context.prisma directly in field resolvers — use context.loaders
  • NEVER return raw database errors to the client — map to user-friendly GraphQLError
  • NEVER skip the extensions.code on GraphQL errors — clients need machine-readable codes
  • NEVER define types inline in resolvers — use SDL .graphql files and codegen
  • NEVER use Apollo Server 3 patterns with AS4 — the context API changed
  • NEVER use graphql-subscriptions PubSub in production with multiple instances — use Redis PubSub
  • NEVER disable persisted queries in production (enable APQ for performance)
  • NEVER expose introspection in production (introspection: process.env.NODE_ENV !== 'production')
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall