Technical RFCs

RFCs (Request for Comments) are detailed technical proposals that invite feedback before implementation. They're used for significant changes that affect multiple teams or systems.

When to Write an RFC

Write an RFC	Don't Need RFC
New service or major feature	Bug fixes
Breaking API changes	Minor refactoring
New technology adoption	Localized changes
Cross-team dependencies	Well-established patterns
Security-critical changes	Routine maintenance

RFC Template

# RFC: Implement GraphQL Federation

**Author:** Jane Smith (@jsmith)  
**Status:** Under Review  
**Created:** 2024-02-01  
**Last Updated:** 2024-02-10  
**Reviewers:** @engineering-leads, @platform-team

## Summary

Implement GraphQL Federation to create a unified API layer across 
our microservices, replacing the current REST-based BFF approach.

## Motivation

### Current Problems
1. Multiple BFFs duplicate logic and create maintenance burden
2. Mobile and web teams request different data shapes
3. Over-fetching wastes bandwidth (critical for mobile)
4. Adding new fields requires BFF changes and deployments

### Goals
- Single, flexible API for all clients
- Reduce BFF maintenance overhead by 60%
- Enable client teams to query exactly what they need
- Maintain service autonomy (each team owns their subgraph)

### Non-Goals
- Replace all REST APIs (internal service-to-service stays REST)
- Real-time subscriptions (future RFC)

## Detailed Design

### Architecture Overview

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Web App │ │ Mobile App │ │ Partner API │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌──────▼──────┐ │ Gateway │ │ (Apollo) │ └──────┬──────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Users │ │ Orders │ │ Products │ │ Subgraph │ │ Subgraph │ │ Subgraph │ └─────────────┘ └─────────────┘ └─────────────┘

### Subgraph Ownership
- **Users Subgraph**: Identity team owns User, Authentication types
- **Orders Subgraph**: Commerce team owns Order, Payment types
- **Products Subgraph**: Catalog team owns Product, Category types

### Schema Stitching Example

```graphql
# Users Subgraph
type User @key(fields: "id") {
  id: ID!
  email: String!
  name: String!
}

# Orders Subgraph
type Order @key(fields: "id") {
  id: ID!
  user: User!  # Resolved via federation
  items: [OrderItem!]!
  total: Money!
}

extend type User @key(fields: "id") {
  id: ID! @external
  orders: [Order!]!  # Extend User with orders
}

Query Resolution Flow

1. Client sends query to Gateway
2. Gateway creates query plan
3. Gateway fetches from relevant subgraphs
4. Gateway assembles response
5. Single response returned to client

Implementation Plan

Phase 1: Foundation (Weeks 1-2)

• Set up Apollo Gateway
• Create Users subgraph (read-only)
• Establish CI/CD pipeline for schema validation

Phase 2: Core Subgraphs (Weeks 3-4)

• Products subgraph
• Orders subgraph (read-only)
• Integration testing framework

Phase 3: Mutations (Weeks 5-6)

• Order creation via GraphQL
• User profile updates
• Error handling standardization

Phase 4: Migration (Weeks 7-8)

• Migrate web app to GraphQL
• Migrate mobile app
• Deprecate old BFF endpoints

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Performance regression	Medium	High	Implement DataLoader, query complexity limits
Team learning curve	High	Medium	Training sessions, pair programming
Schema conflicts	Medium	Medium	Schema review process, automated validation
Gateway as bottleneck	Low	High	Horizontal scaling, caching

Alternatives Considered

1. Keep REST BFFs

• Pros: Team familiarity, no migration
• Cons: Doesn't solve current problems
• Why rejected: Maintenance burden continues to grow

2. gRPC with Protobuf

• Pros: Strong typing, efficient binary format
• Cons: Poor browser support, requires code generation
• Why rejected: Client teams prefer GraphQL flexibility

3. Build Custom API Gateway

• Pros: Full control
• Cons: Significant development effort, maintenance burden
• Why rejected: Apollo Federation is mature, well-supported

Security Considerations

• Query depth limiting to prevent DoS
• Field-level authorization via directives
• Rate limiting at gateway level
• Audit logging for sensitive queries

Success Metrics

• BFF maintenance time reduced by 60%
• API response payload size reduced by 40%
• Client team satisfaction score > 4/5
• P95 latency within 10% of current BFF

Open Questions

1. How do we handle file uploads?
2. Should we implement persisted queries from day one?
3. What's our versioning strategy for breaking schema changes?

References

• Apollo Federation docs
• Netflix GraphQL Federation
• Internal: ADR-015 API Strategy

## RFC Review Process

```mermaid
sequenceDiagram
    participant Author
    participant Reviewers
    participant Team
    participant Approvers
    
    Author->>Reviewers: Submit RFC
    Reviewers->>Author: Initial feedback
    Author->>Reviewers: Address comments
    Reviewers->>Team: Broader review
    Team->>Author: Additional feedback
    Author->>Approvers: Request approval
    Approvers->>Author: Approved/Changes requested
    Author->>Team: Implementation begins

RFC States

Draft → Under Review → Approved → Implementing → Completed
                    ↘ Rejected
                    ↘ Withdrawn

Best Practices

1. Get Early Feedback: Share draft before formal submission
2. Be Specific: Include concrete examples and code
3. Address Concerns: Respond to all reviewer comments
4. Set Deadlines: Define review period (typically 1-2 weeks)
5. Document Decisions: Update RFC with resolution of open questions

Key Takeaways

1. RFCs Enable Collaboration: Get input before committing to a direction
2. Document Trade-offs: Show what was considered and why
3. Include Implementation Plan: Make the path to completion clear
4. Define Success: How will you know the RFC achieved its goals?
5. Keep Updated: RFC should reflect current state of the proposal

---

💡 Flashcard

What is the difference between an ADR and an RFC?

Click to reveal answer

✅ Answer

ADR documents a decision that has been made and its rationale. RFC is a proposal seeking feedback before a decision is made. ADRs are shorter and focused on the decision; RFCs are detailed proposals with implementation plans.

Click to see question

💡 Flashcard

When should you write an RFC instead of just implementing?

Click to reveal answer

✅ Answer

Write an RFC for significant changes that affect multiple teams, introduce new technologies, have security implications, require breaking changes, or need cross-team coordination and buy-in.

Click to see question

Loading quiz...