# asucicrepo/st-louis-zoo architecture

> Architecture diagram of the GitHub repository asucicrepo/st-louis-zoo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asucicrepo/st-louis-zoo
- Repository: https://github.com/asucicrepo/st-louis-zoo

## Overview

##### Main Components

a. Backend (backendV2)
- AWS CDK Infrastructure: Located in the backend directory with files for S3 uploads, Lambda functions, ECS containers, and infrastructure orchestration.
- Lambda Functions: For various tasks such as initializing uploads, generating presigned URLs, finalizing uploads, metadata extraction (using Bedrock/Claude 3.5), OpenSearch integration, and email notifications.
- ECS with Fargate: Handles video processing tasks—video clipping, thumbnail generation, and processing pipelines.
- S3 Storage: Serves as the repository for uploaded videos, intermediate clips, and thumbnails.
- Step Functions: Orchestrates video processing flows once a video enters the system.
- OpenSearch: For storing and serving advanced search metadata.
- Glacier Archive: Implements lifecycle rules for long-term storage, moving videos after 2 days.

b. FrontendV2 (Admin Frontend)
- React Application for Admins: Allows video uploads, metadata tagging (both required and optional), and interacts with Lambda-backed API endpoints.
- AWS Cognito: For Admin Authentication and authorization.

c. Frontend-user (User Flow Frontend)
- React Application for End Users: Provides search and filtering for video content, displays previews and metadata, and includes video access request forms.
- Email Service: Used to notify admins when a user requests full-access to a video.

##### Relationships and Interactions

- The Admin UI (from frontendV2) communicates via API Gateway endpoints to the backend. API calls trigger Lambda functions which initialize uploads, return presigned URLs from S3, and finalize multipart uploads.
- Once a video upload is complete, the S3 bucket triggers a downstream processing pipeline using AWS Step Functions. This workflow coordinates between ECS tasks (for processing video clips and thumbnails) and additional Lambda functions (for AI-based metadata extraction and OpenSearch updates).
- The processed metadata is indexed in OpenSearch to support the advanced search functionality available in the user-facing frontend.
- The User Frontend (from frontend-user) consumes data (search results, video clips, metadata) through APIs. It also provides functionality for submitting video access requests, which in turn triggers email notifications to the administrators.
- Authentication for Admin access is handled by AWS Cognito, while the AWS CDK orchestrates the deployment and configuration of all infrastructure components.

##### Architectural Patterns and Design Principles

- Microservices and Function-as-a-Service (FaaS): Multiple Lambda functions handling discrete tasks.
- API Gateway Pattern: To manage API calls between the UI and backend services.
- Event-Driven Architecture: S3 triggers and Step Functions to automatically process uploads.
- Separation of Concerns: Distinct projects for Admin and User functionalities, enabling maintenance and scalability.
- Cloud-Native Infrastructure-as-Code (AWS CDK): Organizes infrastructure components and deployment pipelines.

##### Relevant Technologies & Frameworks

- AWS Services: Lambda, ECS/Fargate, S3, Step Functions, OpenSearch, Glacier Deep Archive, Cognito, and SES (for email).
- Infrastructure-as-Code: AWS CDK (backendV2)
- Frontend: React for both the admin (frontendV2) and user (frontend-user) interfaces.
- Other Tools: Docker (for ECS containers) and AWS CLI/CDK tools for deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure
    CDKInfra["AWS CDK Infrastructure"]:::infra

    %% Frontend Layer
    subgraph "Frontend"
        AdminFrontend["Admin Frontend – React"]:::admin
        Cognito["Cognito (Authentication)"]:::infra
        UserFrontend["User Frontend – React"]:::user
    end

    %% API & Upload Layer
    subgraph "API & Upload"
        APIGateway["API Gateway"]:::API
        LambdaInit["Lambda: Initialize Upload"]:::lambda
        LambdaPresign["Lambda: Presigned URL"]:::lambda
        LambdaFinalize["Lambda: Finalize Upload"]:::lambda
    end

    %% Backend Storage & Orchestration Layer
    subgraph "Backend Storage & Orchestration"
        S3Storage["S3 (Storage)"]:::storage
        LambdaStepTrigger["Lambda: Step Functions Trigger"]:::lambda
        StepFunctions["Step Functions"]:::orchestration
    end

    %% Processing Pipeline Layer
    subgraph "Processing Pipeline"
        ECSVidProc["ECS/Fargate (Video Processing)"]:::ecs
        LambdaMetadata["Lambda: Metadata Extraction"]:::lambda
        LambdaOpenSearch["Lambda: OpenSearch Integration"]:::lambda
        Glacier["Glacier (Archive)"]:::storage
    end

    %% Search & Notification Layer
    subgraph "Search & Notification"
        LambdaSearchResults["Lambda: Get Search Results"]:::lambda
        OpenSearch["OpenSearch (Metadata)"]:::storage
        LambdaEmail["Lambda: Email Notification"]:::lambda
        EmailService["Email Notification Service"]:::orchestration
    end

    %% Deployment Connections from CDK Infrastructure
    CDKInfra -->|"deploys"| APIGateway
    CDKInfra -->|"deploys"| LambdaInit
    CDKInfra -->|"deploys"| S3Storage
    CDKInfra -->|"deploys"| StepFunctions
    CDKInfra -->|"deploys"| ECSVidProc
    CDKInfra -->|"deploys"| LambdaMetadata
    CDKInfra -->|"deploys"| LambdaEmail

    %% Admin Flow
    AdminFrontend -->|"authenticates"| Cognito
    Cognito -->|"calls_API"| APIGateway
    APIGateway -->|"triggers"| LambdaInit
    LambdaInit -->|"calls"| LambdaPresign
    LambdaPresign -->|"calls"| LambdaFinalize
    LambdaFinalize -->|"uploads"| S3Storage

    %% Backend Processing Flow
    S3Storage -->|"triggers"| LambdaStepTrigger
    LambdaStepTrigger -->|"orchestrates"| StepFunctions
    StepFunctions -->|"executes"| ECSVidProc
    StepFunctions -->|"executes"| LambdaMetadata
    LambdaMetadata -->|"indexes"| LambdaOpenSearch
    LambdaOpenSearch -->|"stores"| OpenSearch
    S3Storage -->|"archives"| Glacier

    %% User Flow
    UserFrontend -->|"queries"| LambdaSearchResults
    LambdaSearchResults -->|"queries"| OpenSearch
    UserFrontend -->|"notifies"| LambdaEmail
    LambdaEmail -->|"emails"| EmailService

    %% Click Events for Component Mapping
    click CDKInfra "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/cdk.json"
    click CDKInfra "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lib/multipart_s3_upload-stack.ts"
    click CDKInfra "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/bin/multipart_s3_upload.ts"
    click LambdaInit "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/initialize.js"
    click LambdaPresign "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/getPreSignedUrls.js"
    click LambdaPresign "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/getPreSignedTAUrls.js"
    click LambdaPresign "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/makePreSignedUrls.js"
    click LambdaFinalize "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/finalize.js"
    click LambdaMetadata "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/bedrockClaudeLambda/getMetadataFromBedrockClaude.py"
    click LambdaOpenSearch "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/opensearchLambda/opensearchCollectionEntry.py"
    click LambdaSearchResults "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/getSearchResultsLambda/getSearchResults.py"
    click LambdaEmail "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/sendEmailLambda/sendEmail.py"
    click LambdaStepTrigger "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/lambda/stepFuncTrigger.js"
    click ECSVidProc "https://github.com/asucicrepo/st-louis-zoo/blob/master/backendV2/ecs/videoProcessing.py"
    click AdminFrontend "https://github.com/asucicrepo/st-louis-zoo/tree/master/frontendV2/"
    click UserFrontend "https://github.com/asucicrepo/st-louis-zoo/tree/master/frontend-user/"

    %% Styles
    classDef admin fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef user fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef lambda fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef ecs fill:#f94144,stroke:#000,stroke-width:2px;
    classDef storage fill:#577590,stroke:#000,stroke-width:2px;
    classDef orchestration fill:#277da1,stroke:#000,stroke-width:2px;
    classDef infra fill:#9d4edd,stroke:#000,stroke-width:2px;
    classDef API fill:#43aa8b,stroke:#000,stroke-width:2px;
```
