# chunyenhuang/piggy-bank-of-happiness architecture

> Architecture diagram of the GitHub repository chunyenhuang/piggy-bank-of-happiness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chunyenhuang/piggy-bank-of-happiness
- Repository: https://github.com/chunyenhuang/piggy-bank-of-happiness

## Overview

##### Project type and purpose
- This is a full-stack, multi-platform “happiness bankbook” application for non-profit child-welfare organizations.
- It comprises two frontends—Web (React) and Mobile (React Native/Expo)—and a serverless AWS backend managed via Amplify (GraphQL/API, Lambda, Cognito, DynamoDB, S3).

##### High-level file-structure analysis
- Top-level “mobile” and “web” directories hold the two client apps.
- “amplify/backend/api” contains AppSync GraphQL schemas and AdminQueries.
- “amplify/backend/function” holds multiple Lambda functions (e.g., eventTracking, organizationApplication, pointOperation, userOperation, postConfirmation).
- “amplify/backend/storage/avatars” houses an S3 bucket definition.
- “data” and “scripts” contain seed and deployment tooling.

##### README insights
- Confirms use of AWS Amplify for auth (Cognito), GraphQL API, storage, and hosting.
- Points to design, development, deployment docs.
- Emphasizes multi-environment setup (develop vs production).

##### Main components and interactions
a. Frontends
- Web App (React)
- Mobile App (React Native via Expo)
b. Authentication
- Amazon Cognito User Pool & Identity Pool
c. API
- AWS AppSync GraphQL endpoint
- “piggybankofhappiness” API for core domain
- “AdminQueries” API for user-management operations
d. Business Logic
- AWS Lambda functions triggered by AppSync resolvers (one function per domain: eventTracking, pointOperation, etc.)
- Post-confirmation trigger for user signup
e. Data storage
- Amazon DynamoDB (auto-generated tables for GraphQL types)
- Amazon S3 bucket for avatars and media
f. Tooling & CI/CD
- AWS Amplify Console for build/deploy (amplify.yml)
- Local scripts under “scripts” for provider-info and tag updates
- Data seeding scripts under “data”

##### Architectural patterns
- Serverless microservices: each domain function lives in its own Lambda.
- GraphQL façade: AppSync dispatches queries/mutations to DynamoDB or Lambda.
- Event-driven: Lambdas triggered by AppSync or Cognito events (post-confirmation).
- Infrastructure as Code: CloudFormation templates under amplify/backend.

##### Essential architectural elements to capture
- Clear separation of frontend vs backend.
- Authentication flow through Cognito.
- GraphQL API as the façade and how it routes to DynamoDB vs Lambdas.
- Serverless functions representing core business domains.
- Persistent storage: DynamoDB and S3.
- CI/CD integration via Amplify Console.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients and Tooling (External)
    Web["Web App (React)"]:::frontend
    Mobile["Mobile App (React Native)"]:::frontend
    Data["Data Seeding Scripts"]:::external
    Scripts["Deployment & Tagging Scripts"]:::external

    %% AWS Cloud Boundary
    subgraph "AWS Cloud"
        %% Authentication
        subgraph Auth
            CP["Cognito User Pool & Identity Pool"]:::auth
            UG["Cognito User Pool Groups"]:::auth
        end

        %% APIs
        AppSyncCore["AppSync Core GraphQL API"]:::compute
        AppSyncAdmin["AppSync AdminQueries API"]:::compute

        %% Business Logic Lambdas
        subgraph "Business Logic (Lambdas)"
            ET["EventTracking Lambda"]:::compute
            OA["OrganizationApplication Lambda"]:::compute
            PO["PointOperation Lambda"]:::compute
            UO["UserOperation Lambda"]:::compute
            PC["PostConfirmation Lambda"]:::compute
            AQ["AdminQueries Lambda"]:::compute
        end

        %% Data Stores
        Dynamo["DynamoDB Tables"]:::db
        S3["S3 Avatars Bucket"]:::storage

        %% CI/CD
        AmplifyConsole["Amplify Console (CI/CD)"]:::ci
    end

    %% Authentication Flow
    Web -->|Cognito Auth| CP
    Mobile -->|Cognito Auth| CP
    CP -->|Uses Groups| UG

    %% API Calls
    Web -->|GraphQL Query/Mutation| AppSyncCore
    Mobile -->|GraphQL Query/Mutation| AppSyncCore
    Web -->|GraphQL AdminOps| AppSyncAdmin

    %% AppSync Routing
    AppSyncCore -->|Direct Resolver| Dynamo
    AppSyncCore -->|Lambda Resolver| ET
    AppSyncCore -->|Lambda Resolver| OA
    AppSyncCore -->|Lambda Resolver| PO
    AppSyncCore -->|Lambda Resolver| UO
    AppSyncAdmin -->|Invoke| AQ

    %% Post-Confirmation Trigger
    CP -->|Post Confirmation Trigger| PC

    %% Lambda Data Flow
    ET -->|Read/Write| Dynamo
    OA -->|Read/Write| Dynamo
    PO -->|Read/Write| Dynamo
    UO -->|Read/Write| Dynamo
    PC -->|Write| Dynamo
    AQ -->|Read/Write| Dynamo

    %% Storage Access
    Web -->|Upload/Fetch| S3
    Mobile -->|Upload/Fetch| S3

    %% CI/CD Integration
    Data -->|Seed & Configure| AmplifyConsole
    Scripts -->|Deploy & Tag| AmplifyConsole
    AmplifyConsole -->|Deploy Cloud Resources| CP
    AmplifyConsole -->|Deploy Cloud Resources| AppSyncCore
    AmplifyConsole -->|Deploy Cloud Resources| AppSyncAdmin
    AmplifyConsole -->|Deploy Cloud Resources| ET
    AmplifyConsole -->|Deploy Cloud Resources| OA
    AmplifyConsole -->|Deploy Cloud Resources| PO
    AmplifyConsole -->|Deploy Cloud Resources| UO
    AmplifyConsole -->|Deploy Cloud Resources| PC
    AmplifyConsole -->|Deploy Cloud Resources| AQ
    AmplifyConsole -->|Deploy Cloud Resources| Dynamo
    AmplifyConsole -->|Deploy Cloud Resources| S3

    %% Click Events
    click Web "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/web/"
    click Mobile "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/mobile/"
    click CP "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/auth/piggybankofhappinesscf2e2c90/"
    click UG "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/auth/userPoolGroups/"
    click AppSyncCore "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/api/piggybankofhappiness/"
    click AppSyncAdmin "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/api/AdminQueries/"
    click ET "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/eventTracking/"
    click OA "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/organizationApplication/"
    click PO "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/pointOperation/"
    click UO "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/userOperation/"
    click PC "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/piggybankofhappinesscf2e2c90PostConfirmation/"
    click AQ "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/function/AdminQueries71325e9b/"
    click Dynamo "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/api/piggybankofhappiness/stacks/"
    click S3 "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/amplify/backend/storage/avatars/"
    click AmplifyConsole "https://github.com/chunyenhuang/piggy-bank-of-happiness/blob/develop/amplify.yml"
    click Data "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/data/"
    click Scripts "https://github.com/chunyenhuang/piggy-bank-of-happiness/tree/develop/scripts/"

    %% Styles
    classDef frontend fill:#a8f0c6,stroke:#2e7d32,color:#000;
    classDef compute fill:#bbdefb,stroke:#1565c0,color:#000;
    classDef db fill:#ffe0b2,stroke:#ef6c00,color:#000;
    classDef storage fill:#e1bee7,stroke:#6a1b9a,color:#000;
    classDef auth fill:#eceff1,stroke:#607d8b,color:#000;
    classDef ci fill:#cfd8dc,stroke:#455a64,color:#000;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#000;
```
