# awslabs/aws-api-gateway-developer-portal architecture

> Architecture diagram of the GitHub repository awslabs/aws-api-gateway-developer-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/aws-api-gateway-developer-portal
- Repository: https://github.com/awslabs/aws-api-gateway-developer-portal

## Overview

##### Project Type and Purpose
- This is a full-stack, serverless developer portal for AWS API Gateway.
- Purpose: Provide an interactive, self-service portal (React SPA) for API consumers to browse docs, register/login (Cognito), obtain API keys, “Try It Out,” view metrics, generate SDKs, and submit feedback.

##### High-Level Architecture Inferred from File Tree & README
- Frontend (“dev-portal” directory): React application built and deployed as static assets to S3, served through CloudFront (with optional custom domain).
- Backend (“lambdas” directory): Multiple Lambda functions behind an API Gateway REST API. These include:
- Authentication/identity triggers (Cognito pre-signup, post-confirmation, post-authentication)
- Core routes for catalog, accounts, subscriptions, feedback, marketplace workflows, SDK generation, asset uploads
- Auxiliary lambdas (catalog-updater, static-asset-uploader, user/group import-export, CloudFront security, common shared layer)
- Infrastructure as code (cloudformation/template.yaml): Defines API Gateway, Lambda functions, Cognito User Pool, DynamoDB tables (Customers, UsagePlans), S3 buckets (static assets, artifacts), CloudFront distribution, IAM roles, Route53 (optional).
- Deployment scripts: SAM packaging/deploy, SAR option, custom scripts under “scripts/” for development workflows.

##### Core Components
a. Static Website Hosting
- S3 bucket (DevPortalSiteS3Bucket) storing React build
- CloudFront distribution + optional Route53 custom domain
b. Client Application
- Browser runs React SPA, loads JS/CSS from CloudFront • Calls API endpoints
c. API Layer
- API Gateway REST API (single entry point, proxies to Lambdas)
d. Compute Layer (Lambda functions)
- User management triggers (Cognito PreSignUp, PostConfirm, PostAuth)
- Admin/Account management lambdas (approve/deny/promote/resend invite)
- Catalog management (list, import generic swagger/OpenAPI, visibility toggles, SDK generation)
- Subscription flows (subscribe/unsubscribe usage plans, marketplace confirm)
- Feedback service
- Asset uploader (push React build and custom content to S3)
- Catalog-updater (poll or trigger to refresh API specs)
- Shared utilities layer (common code)
e. Data Stores & External Services
- DynamoDB tables (Customers, API catalog, Usage plans, feedback)
- Cognito User Pool & Identity Pool (authentication/authorization)
- AWS API Gateway usage plans & API keys
- S3 (artifacts bucket for Lambda zips, static assets bucket)
- CloudWatch Logs (for Lambda tracing)
- (Optional) AWS Marketplace SNS topic and listener for subscription events

##### Relationships & Data Flows
- User → Browser → CloudFront → S3 static site
- SPA → API Gateway → specific Lambda (based on route)
- Lambda ↔ DynamoDB (read/write user profiles, API catalog entries, usage records)
- Lambda ↔ API Gateway service APIs (create/list API keys, usage plan associations, export SDK)
- React SPA ↔ Cognito SDK calls for sign-up, login, token refresh
- Catalog-updater Lambda triggered (e.g., event or cron) → fetch external Swagger/OpenAPI → store in DynamoDB/S3
- Asset-uploader Lambda triggered post-build → upload new SPA build to S3

##### Architectural Patterns & Design Principles
- Serverless microservices: each Lambda implements a focused function/route
- Single-page application (SPA) decoupled from backend API
- Infrastructure as code (CloudFormation/SAM) for reproducible deployment
- Layered security: Cognito for auth, IAM roles for Lambdas, CloudFront HTTPS
- Event-driven asset and catalog updates via Lambda triggers/SNS

##### Essential Elements
- Clear labels (e.g., “User,” “React SPA,” “API Gateway REST API,” “Lambda: AccountRoutes,” “DynamoDB: CustomersTable”)
- Arrowheads for data flow direction

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Client
    User["User"]:::client
    Browser["Browser (React SPA)"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        CF["CloudFront Distribution"]:::static
        S3Static["S3: DevPortalSiteS3Bucket"]:::static
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGW["API Gateway REST API"]:::api
    end

    %% Compute Layer
    subgraph "Compute Layer"
        direction TB
        PreSignup["Lambda: Cognito Pre-SignUp Trigger"]:::compute
        PostConfirm["Lambda: Cognito Post-Confirmation Trigger"]:::compute
        PostAuth["Lambda: Cognito Post-Authentication Trigger"]:::compute
        BackendRoutes["Lambda: Backend Routes (API Proxy)"]:::compute
        AssetUploader["Lambda: Static Asset Uploader"]:::compute
        CatalogUpdater["Lambda: Catalog Updater"]:::compute
        CFSSecurity["Lambda: CloudFront Security"]:::compute
        UserGroupImport["Lambda: User/Group Importer"]:::compute
        UserGroupExport["Lambda: User/Group Exporter v3"]:::compute
        SNSListener["Lambda: Marketplace SNS Listener"]:::compute
        CommonLayer["Common Utilities Layer"]:::compute
    end

    %% Data Stores & Identity
    subgraph "Data Stores & Identity"
        direction TB
        DynamoDB["DynamoDB Tables"]:::datastore
        CognitoPool["Cognito User Pool"]:::identity
        SNS["AWS SNS Topic"]:::external
    end

    %% Deployment & IaC
    subgraph "Deployment & IaC"
        direction TB
        SAM["SAM Packaging/Deployment"]:::infra
        Scripts["Custom Scripts"]:::infra
        SAR["AWS SAR Deployment"]:::infra
        IaC["CloudFormation Template"]:::infra
    end

    %% Relationships
    User -->|"uses"| Browser
    Browser -->|"HTTPS"| CF
    CF -->|"HTTPS"| S3Static
    Browser -->|"REST API calls"| APIGW
    Browser -->|"Cognito SDK"| CognitoPool

    APIGW -->|"invokes"| BackendRoutes
    BackendRoutes -->|"read/write"| DynamoDB
    BackendRoutes -->|"AWS Service APIs"| APIGW

    CognitoPool -->|"triggers"| PreSignup
    CognitoPool -->|"triggers"| PostConfirm
    CognitoPool -->|"triggers"| PostAuth

    AssetUploader -->|"uploads assets"| S3Static
    CatalogUpdater -->|"updates catalog"| DynamoDB
    CatalogUpdater -->|"fetches OpenAPI"| externalAPI[(External API)]
    SNSListener -->|"processes SNS events"| SNS

    CFSSecurity -->|"secures"| CF

    UserGroupImport -->|"imports/exports"| DynamoDB
    UserGroupExport -->|"imports/exports"| DynamoDB

    CommonLayer -->|"shared code for"| BackendRoutes
    CommonLayer -->|"shared code for"| all

    SAM -->|"packages artifacts"| IaC
    Scripts -->|"deploys stack"| IaC
    SAR -->|"deploys SAR"| IaC
    IaC -->|"provisions"| APIGW
    IaC -->|"provisions"| PreSignup
    IaC -->|"provisions"| PostConfirm
    IaC -->|"provisions"| PostAuth
    IaC -->|"provisions"| DynamoDB
    IaC -->|"provisions"| CognitoPool
    IaC -->|"provisions"| S3Static
    IaC -->|"provisions"| CF

    %% Click Events
    click IaC "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/cloudformation/template.yaml"
    click CF "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/cloudformation/template.yaml"
    click S3Static "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/cloudformation/template.yaml"
    click APIGW "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/cloudformation/template.yaml"
    click BackendRoutes "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/backend/index.js"
    click PreSignup "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/cognito-pre-signup-trigger/index.js"
    click PostConfirm "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/cognito-post-confirmation-trigger/index.js"
    click PostAuth "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/cognito-post-authentication-trigger/index.js"
    click AssetUploader "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/static-asset-uploader/index.js"
    click CatalogUpdater "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/catalog-updater/index.js"
    click CFSSecurity "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/cloudfront-security/index.js"
    click UserGroupImport "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/user-group-importer/index.js"
    click UserGroupExport "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/user-group-exporter-v3/index.js"
    click SNSListener "https://github.com/awslabs/aws-api-gateway-developer-portal/blob/main/lambdas/listener/index.js"
    click CommonLayer "https://github.com/awslabs/aws-api-gateway-developer-portal/tree/main/lambdas/common-layer/nodejs"
    click Browser "https://github.com/awslabs/aws-api-gateway-developer-portal/tree/main/dev-portal/src"

    %% Styles
    classDef static fill:#cce4f6,stroke:#4aa3df,color:#000
    classDef client fill:#d4edda,stroke:#28a745,color:#000
    classDef api fill:#b8daff,stroke:#0056b3,color:#000
    classDef compute fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef datastore fill:#e5ccff,stroke:#800080,color:#000
    classDef identity fill:#f8d7da,stroke:#dc3545,color:#000
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef external fill:#fdfd96,stroke:#ffd700,color:#000
```
