Skip to content

API Gateway: System Overview and Technical Requirements

Version Date Author Change Description
1.0 2025-09-11 Senior Systems Analyst Initial Draft for local password authentication.
2.0 2025-09-11 Senior Systems Analyst Major revision to align with Google SSO. Rewrote Authentication section for OAuth 2.0 flow.

1.0 Introduction

1.1 Purpose of this Document

This document provides the high-level technical requirements and system design for the API Gateway. It serves as the primary technical reference for this component, defining its role within the application architecture, its core responsibilities, and its interactions with other services.

The intended audience for this document includes system architects, backend developers responsible for implementing the gateway and its connected services, and frontend developers who will consume the API it exposes.

1.2 System Overview and Role in Architecture

The API Gateway is a critical infrastructure component that acts as the single, unified entry point for all client-side requests originating from the Frontend enterprise console. It serves as a façade, abstracting the internal microservices architecture (initially consisting of the AuthService) from the client, as outlined in ADR-0002. This service is undergoing migration to Nest.js and TypeScript to enhance maintainability and type safety.

Architecture & Technology Stack

Architectural Style

The API Gateway is a stateless, containerized microservice designed for high availability and horizontal scalability. It acts as a reverse proxy and API aggregator, shielding internal services from direct client exposure.

Technology Stack

Component Technology Purpose
Runtime Environment Nest.js (TypeScript) Provides a structured, scalable, and type-safe backend framework for handling API requests and routing.
API Protocol (External) HTTP RESTful API Exposes a standard, developer-friendly interface to the frontend application.
API Protocol (Internal) gRPC Used for high-performance, strongly-typed communication with backend microservices.

Its primary architectural roles are:

  1. Single Entry Point: The gateway provides a single, consistent, and secure DNS endpoint for the frontend application. This simplifies client-side configuration and network security rules, as only the gateway needs to be publicly exposed.
  2. Protocol Translation: The gateway is responsible for translating protocols between the client and backend services. It exposes a standard, developer-friendly HTTP RESTful API to the frontend, while communicating with backend services using the high-performance gRPC protocol, as decided in ADR-0003.
  3. Centralized Cross-Cutting Concerns: It offloads common responsibilities from the individual microservices, centralizing them for consistent application. These include:
  4. Orchestrating the OAuth 2.0 authentication flow.
  5. Validating session tokens on subsequent requests.
  6. High-level Authorization Checks.
  7. Request/Response Logging and Auditing.

2.0 Core Responsibilities and Functionality

2.1 Request Routing and Service Discovery

The gateway will inspect the path and HTTP method of every incoming request to determine which backend gRPC service and method should handle it. This mapping of RESTful endpoints to gRPC calls will be explicitly defined.

  • Reference: See routing_rules.md for the complete mapping table.

2.2 Protocol Translation (REST <-> gRPC)

A core function is the seamless transformation of requests and responses:

  • Incoming Request: An HTTP request with a JSON body is received. The gateway will marshal this JSON payload into the corresponding Protobuf message required by the target gRPC service.
  • Outgoing Response: A Protobuf message received from a gRPC service is unmarshalled into a JSON payload, which is then sent back to the client in the HTTP response.

2.3 Authentication and Session Handling (Google SSO Flow)

The gateway is the central orchestrator of the user authentication process. It does not handle credentials directly but manages the OAuth 2.0 redirect flow with Google.

  1. Initiation: When a user needs to log in, the frontend directs them to a specific endpoint on the gateway (e.g., GET /api/v1/auth/google/login). The gateway's sole responsibility at this endpoint is to generate the correct authentication URL for Google and issue an HTTP 302 Redirect to the user's browser, sending them to Google's login page.
  2. Callback Handling: After the user authenticates with Google, Google redirects them back to a designated callback endpoint on the gateway (e.g., GET /api/v1/auth/google/callback). This request includes a single-use authorization_code.
  3. Session Creation: The gateway receives this authorization_code and makes a synchronous gRPC call to the AuthService.HandleGoogleAuthCallback method. The AuthService is responsible for exchanging the code, performing JIT provisioning, and returning a new application session token.
  4. Token Issuance: Upon a successful response from the AuthService, the gateway sets the received session token in a secure, HTTP-only cookie in the user's browser and then redirects them to the main application dashboard.
  5. Subsequent Request Validation: For all subsequent requests to protected endpoints, the gateway will extract the session token from the cookie and make a AuthService.ValidateSession gRPC call. If the session is invalid, the request is rejected with an HTTP 401 Unauthorized status.

2.4 Authorization / Permission Enforcement

After successful authentication, the gateway will also serve as a coarse-grained authorization enforcement point.

  1. The routing rules will specify the permission required for each endpoint (e.g., admin:user:invite is required for POST /api/v1/users/invite).
  2. Before forwarding a request to its target service, the gateway will use the validated user_id from the session to make a AuthService.CheckPermission gRPC call.
  3. If the permission check fails, the gateway will reject the request with an HTTP 403 Forbidden status code.

2.5 Centralized Error Handling

The gateway will provide a consistent error response format to the client. It will translate different error conditions into standard HTTP status codes:

  • 400 Bad Request: Invalid JSON, missing required fields, or malformed requests.
  • 401 Unauthorized: Missing, invalid, or expired session token on an API call.
  • 403 Forbidden: The user is authenticated but lacks the specific permission for the action.
  • 404 Not Found: The requested endpoint does not exist.
  • 500 Internal Server Error: An unexpected error occurred within the gateway itself.
  • 503 Service Unavailable: The target backend gRPC service is down or unreachable.

3.0 Non-Functional Requirements

  • Performance: The latency introduced by the gateway should be minimal, ideally adding no more than 10-20ms to the total request time.
  • Scalability: The gateway must be a stateless service, allowing it to be horizontally scaled behind a load balancer to handle increased traffic.
  • Security: The gateway will handle TLS termination for all incoming traffic, encrypting communication from the client. It protects the internal gRPC services from direct exposure to the public internet.
  • Observability: The gateway must generate structured logs for every request and response, including key information like the request path, status code, latency, and user ID (if authenticated).
  • REST API Contract
    The formal definition of every RESTful endpoint exposed to the frontend.
  • Routing Rules
    A detailed table mapping each REST endpoint to its backend gRPC service.
  • Sequence Diagrams
    Visual diagrams illustrating key request flows.