# nasa-impact/veda-backend architecture

> Architecture diagram of the GitHub repository nasa-impact/veda-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nasa-impact/veda-backend
- Repository: https://github.com/nasa-impact/veda-backend

## Overview

##### Project type and purpose
- This is a full-stack, serverless backend for a SpatioTemporal Asset Catalog (STAC).
- It uses AWS CDK to deploy a VPC, RDS (PgSTAC), serverless APIs (STAC API, TiTiler raster API, ingest API), a DynamoDB queue, and an S3 website.

##### File structure
- Top-level CDK constructs under directories:
- network/infrastructure (VPC, subnets, gateways)
- database/infrastructure (RDS with pgstac)
- ingest_api/infrastructure (API Lambda + DynamoDB)
- stac_api/infrastructure (STAC API Lambda + API Gateway)
- raster_api/infrastructure (TiTiler Lambda + API Gateway)
- s3_website/infrastructure (static site bucket + CloudFront or S3 website)
- permissions_boundary, standalone_base_infrastructure (shared infra)
- Runtimes for each service under their respective runtime/ directories.
- Common utilities (common/auth) and scripts for local testing, deployment, and maintenance.

##### README for additional insights
- Key technologies: stac-fastapi, pgstac, titiler, titiler-pgstac, AWS Lambda, API Gateway, CDK.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Client["Client"] 
        S3Website["S3 Website"]:::storage
        IngestAPI_GW["Ingest API Gateway"]:::api
        STACAPI_GW["STAC API Gateway"]:::api
        RasterAPI_GW["Raster API Gateway"]:::api
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        IngestAPI_Lambda["Ingest API Lambda"]:::compute
        IngestProcessor["Ingest Processor Lambda"]:::compute
        STACAPI["STAC API Lambda"]:::compute
        RasterAPI["Raster API Lambda"]:::compute
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DynamoDB["DynamoDB Queue"]:::database
        RDS["RDS (PostgreSQL + pgstac)"]:::database
        AssetBucket["S3 Asset Bucket"]:::storage
    end

    %% Networking Layer
    subgraph "Networking (VPC)"
        direction TB
        VPC["VPC"]:::infra
        PublicSubnet["Public Subnet"]:::infra
        PrivateSubnet["Private Subnet"]:::infra
        IGW["Internet Gateway"]:::infra
        NAT["NAT Gateway"]:::infra
    end

    %% Shared Infrastructure
    subgraph "Shared Infrastructure"
        direction TB
        Cognito["Cognito User Pool"]:::auth
        PermissionsBoundary["Permissions Boundary"]:::infra
        StandaloneBase["Standalone Base Infrastructure"]:::infra
        Config["Shared Configuration"]:::infra
        AuthSetup["Auth Utilities"]:::auth
    end

    %% Connections
    Client -->|"requests"| IngestAPI_GW
    Client -->|"requests"| STACAPI_GW
    Client -->|"requests"| RasterAPI_GW
    Client -->|"fetches site"| S3Website

    IngestAPI_GW -->|"invokes"| IngestAPI_Lambda
    STACAPI_GW -->|"invokes"| STACAPI
    RasterAPI_GW -->|"invokes"| RasterAPI

    IngestAPI_Lambda -->|"writes to"| DynamoDB
    DynamoDB -->|"stream event"| IngestProcessor
    IngestProcessor -->|"loads into"| RDS

    STACAPI -->|"queries"| RDS
    RasterAPI -->|"queries metadata"| RDS
    RasterAPI -->|"fetches tiles"| AssetBucket
    STACAPI_GW -->|"authorizer"| Cognito
    IngestAPI_GW -->|"authorizer"| Cognito
    RasterAPI_GW -->|"authorizer"| Cognito

    S3Website -->|"calls API"| STACAPI_GW
    S3Website -->|"calls API"| RasterAPI_GW

    %% VPC connections
    VPC --> PublicSubnet
    VPC --> PrivateSubnet
    PublicSubnet --> IGW
    PublicSubnet --> NAT
    PrivateSubnet --> NAT
    PrivateSubnet --> RDS
    PrivateSubnet --> IngestProcessor

    %% Click Events
    click VPC "https://github.com/nasa-impact/veda-backend/blob/develop/network/infrastructure/construct.py"
    click RDS "https://github.com/nasa-impact/veda-backend/blob/develop/database/infrastructure/construct.py"
    click DynamoDB "https://github.com/nasa-impact/veda-backend/blob/develop/ingest_api/infrastructure/construct.py"
    click IngestAPI_Lambda "https://github.com/nasa-impact/veda-backend/blob/develop/ingest_api/infrastructure/construct.py"
    click IngestProcessor "https://github.com/nasa-impact/veda-backend/blob/develop/ingest_api/runtime/ingestor.py"
    click STACAPI "https://github.com/nasa-impact/veda-backend/blob/develop/stac_api/infrastructure/construct.py"
    click RasterAPI "https://github.com/nasa-impact/veda-backend/blob/develop/raster_api/infrastructure/construct.py"
    click Cognito "https://github.com/nasa-impact/veda-backend/blob/develop/common/auth/veda_auth/main.py"
    click S3Website "https://github.com/nasa-impact/veda-backend/blob/develop/s3_website/infrastructure/construct.py"
    click PermissionsBoundary "https://github.com/nasa-impact/veda-backend/blob/develop/permissions_boundary/infrastructure/construct.py"
    click StandaloneBase "https://github.com/nasa-impact/veda-backend/blob/develop/standalone_base_infrastructure/standalone_app.py"
    click Config "https://github.com/nasa-impact/veda-backend/blob/develop/config.py"
    click AuthSetup "https://github.com/nasa-impact/veda-backend/blob/develop/common/auth/setup.py"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6
    classDef database fill:#DFFFE0,stroke:#228B22
    classDef storage fill:#FFF4CE,stroke:#DAA520
    classDef api fill:#E8F4FF,stroke:#41b6e6
    classDef auth fill:#FFE0E0,stroke:#DC143C
    classDef infra fill:#F0F0F0,stroke:#999999
```
