# saya-setona/letstalk-webapp architecture

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

- Interactive diagram: https://gitdiagram.com/saya-setona/letstalk-webapp
- Repository: https://github.com/saya-setona/letstalk-webapp

## Overview

##### Project type and purpose
- This is a full-stack citizen-facing web application (“Let’s Talk – Citizen WebApp”).
- The front end is a ReactJS/Vite SPA that interfaces with a serverless AWS backend.
- Purpose: Enable citizens to authenticate, report service issues, view updates, make payments, engage in a community hub, and access municipal services.

##### File structure
- **Top level**
- `.env.local`, `package.json`, `vite.config.js`, `README.md`, `letstalk-api-openapi.yaml`
- `aws/` folder containing Cognito setup, DynamoDB scripts, Lambda functions, S3 bucket scripts
- `public/` and `src/` for the React application
- **src/**
- `components/`, `pages/`, `layouts/`, `contexts/`, `hooks/`, `services/` (API calls), `store/` (Redux slices), `translations/`, `utils/`, `theme.js`, `styles/`
- **AWS infra**
- AWS Cognito (authentication)
- AWS Lambda (CRUD operations for users, messages, documents, notifications, service-requests)
- AWS DynamoDB (data storage)
- AWS S3 (static assets and user-uploaded docs)

##### README
- Confirms front end uses React 18 + Vite, Redux Toolkit, Material-UI + custom theme, and will use AWS Amplify to integrate with Cognito and the API.
- Backend is shared and serverless on AWS.
- OpenAPI spec (`letstalk-api-openapi.yaml`) defines REST endpoints.
- Deployment options include AWS Amplify, Netlify/Vercel, or manual S3/CloudFront.

##### Main components
a. **Client Layer**
- Browser (React SPA)
- Bundled and deployed via Vite → S3/CloudFront or Amplify Hosting
b. **Authentication & Authorization**
- AWS Cognito User Pool (Sign-up, login, refresh tokens)
c. **API Gateway Layer** (implicit from OpenAPI spec)
- REST API endpoints defined in `letstalk-api-openapi.yaml`
- Routes requests to Lambda functions
d. **Compute Layer**
- AWS Lambda functions under `aws/lambda/src/*`
- Shared helper code for auth, DynamoDB access, validation, responses
e. **Data Layer**
- AWS DynamoDB tables (users, community-messages, documents, notifications, service-requests)
- Scripts for create/delete/seed under `aws/dynamodb/`
f. **Storage Layer**
- AWS S3 buckets (static assets or user document storage)
g. **CI/CD / Deployment**
- Vite build pipeline (npm scripts)
- AWS CLI / Amplify Console or `aws/lambda/deploy-functions.sh` for Lambdas
- `aws/s3/create-buckets.sh` for storage

##### Relationships and interactions
- The browser fetches `index.html`/JS bundles from the hosting layer.
- SPA calls AWS Cognito for user flows (signup, login, refresh tokens).
- Authenticated API calls go to API Gateway → specific Lambda.
- Lambda uses shared modules to validate tokens, read/write DynamoDB, generate responses.
- Lambdas may read/write user documents from S3.
- Redux in the SPA stores state from API responses.

##### Architectural patterns & principles
- **Serverless microservices**: Each Lambda function handles one specific REST operation.
- **Single Page Application**: Client routing with React Router.
- **Modular front end**: Components, contexts, services, store slices separated by concern.
- **Shared library**: Common auth and DB helpers in `aws/lambda/src/shared`.
- **Infrastructure as code/scripts**: Bash scripts to provision AWS services.
- **OpenAPI-first design**: `letstalk-api-openapi.yaml` drives API schema.

##### Additional notes
- Build/deploy pipeline at the bottom or side: `npm run build` → S3/Amplify → CloudFront distribution.
- Shared modules by showing a “shared code” library that each Lambda references.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        Browser["React SPA\n(src/main.jsx, App.jsx)"]:::client
        public["public/index.html"]:::client
        vite["vite.config.js"]:::client
    end

    subgraph "Frontend Structure"
        components["components/"]:::client
        pages["pages/"]:::client
        layouts["layouts/"]:::client
        contexts["contexts/"]:::client
        hooks["hooks/"]:::client
        services["services/"]:::client
        authService["authService.js"]:::client
        amplifyService["amplifyAuthService.js"]:::client
        storeDir["store/"]:::client
        storeFile["store.js, counterSlice.js"]:::client
        translations["translations/"]:::client
        utils["utils/"]:::client
        authUtils["authUtils.js"]:::client
        jwt["jwtDecode.js"]:::client
        secret["secretHash.js"]:::client
        theme["theme.js"]:::client
        styles["global.css"]:::client
    end

    subgraph "Authentication & Authorization"
        cognito["AWS Cognito\nUser Pool"]:::auth
    end

    subgraph "API Layer"
        openapi["OpenAPI Spec\n(letstalk-api-openapi.yaml)"]:::api
        apiGw["API Gateway"]:::api
    end

    subgraph "Compute Layer"
        subgraph "Lambda Functions"
            login["auth-login"]:::compute
            register["auth-register"]:::compute
            refresh["auth-refresh"]:::compute
            msgs["community-messages"]:::compute
            docs["documents"]:::compute
            notes["notifications"]:::compute
            sr["service-requests"]:::compute
            users["users"]:::compute
        end
        shared["shared helpers"]:::compute
    end

    subgraph "Data Layer"
        usersTbl["Users Table"]:::data
        msgsTbl["CommunityMessages Table"]:::data
        docsTbl["Documents Table"]:::data
        notesTbl["Notifications Table"]:::data
        srTbl["ServiceRequests Table"]:::data
    end

    subgraph "Storage Layer"
        s3static["S3 Bucket\nStatic Assets"]:::storage
        s3uploads["S3 Bucket\nUser Uploads"]:::storage
    end

    subgraph "CI/CD & Deployment"
        build["npm run build"]:::ci
        deploySPA["Deploy to S3/Amplify"]:::ci
        deployLambda["deploy-functions.sh"]:::ci
        s3scripts["create-buckets.sh"]:::ci
        dynamodbScripts["create-tables.sh, delete-tables.sh, seed-tables.sh"]:::ci
    end

    Browser -->|bundles| public
    Browser -->|entry| components
    Browser --> layouts
    Browser --> pages
    Browser --> contexts
    Browser --> hooks
    Browser --> services
    services --> authService
    services --> amplifyService
    Browser --> storeDir
    storeDir --> storeFile
    Browser --> translations
    Browser --> utils
    utils --> authUtils
    utils --> jwt
    utils --> secret
    Browser --> theme
    Browser --> styles

    Browser -->|Sign-up/Login| cognito
    Browser -->|API Calls| apiGw
    openapi --> apiGw
    cognito -->|Verify tokens| apiGw

    apiGw -->|Invoke| login
    apiGw --> register
    apiGw --> refresh
    apiGw --> msgs
    apiGw --> docs
    apiGw --> notes
    apiGw --> sr
    apiGw --> users
    login --> shared
    register --> shared
    refresh --> shared
    msgs --> shared
    docs --> shared
    notes --> shared
    sr --> shared
    users --> shared

    shared -->|DynamoDB queries| usersTbl
    shared --> msgsTbl
    shared --> docsTbl
    shared --> notesTbl
    shared --> srTbl

    Browser -->|Fetch assets| s3static
    shared -->|Get/Put documents| s3uploads

    build --> deploySPA
    deployLambda --> cognito
    deployLambda --> usersTbl
    s3scripts --> s3static
    s3scripts --> s3uploads
    dynamodbScripts --> usersTbl
    dynamodbScripts --> msgsTbl
    dynamodbScripts --> docsTbl
    dynamodbScripts --> notesTbl
    dynamodbScripts --> srTbl

    click Browser "https://github.com/saya-setona/letstalk-webapp/blob/production/src/main.jsx"
    click public "https://github.com/saya-setona/letstalk-webapp/blob/production/public/index.html"
    click vite "https://github.com/saya-setona/letstalk-webapp/blob/production/vite.config.js"
    click components "https://github.com/saya-setona/letstalk-webapp/tree/production/src/components/"
    click pages "https://github.com/saya-setona/letstalk-webapp/tree/production/src/pages/"
    click layouts "https://github.com/saya-setona/letstalk-webapp/tree/production/src/layouts/"
    click contexts "https://github.com/saya-setona/letstalk-webapp/tree/production/src/contexts/"
    click hooks "https://github.com/saya-setona/letstalk-webapp/tree/production/src/hooks/"
    click services "https://github.com/saya-setona/letstalk-webapp/tree/production/src/services/"
    click authService "https://github.com/saya-setona/letstalk-webapp/blob/production/src/services/authService.js"
    click amplifyService "https://github.com/saya-setona/letstalk-webapp/blob/production/src/services/amplifyAuthService.js"
    click storeDir "https://github.com/saya-setona/letstalk-webapp/tree/production/src/store/"
    click storeFile "https://github.com/saya-setona/letstalk-webapp/blob/production/src/store/store.js"
    click translations "https://github.com/saya-setona/letstalk-webapp/tree/production/src/translations/"
    click utils "https://github.com/saya-setona/letstalk-webapp/tree/production/src/utils/"
    click authUtils "https://github.com/saya-setona/letstalk-webapp/blob/production/src/utils/authUtils.js"
    click jwt "https://github.com/saya-setona/letstalk-webapp/blob/production/src/utils/jwtDecode.js"
    click secret "https://github.com/saya-setona/letstalk-webapp/blob/production/src/utils/secretHash.js"
    click theme "https://github.com/saya-setona/letstalk-webapp/blob/production/src/theme.js"
    click styles "https://github.com/saya-setona/letstalk-webapp/blob/production/src/styles/global.css"
    click openapi "https://github.com/saya-setona/letstalk-webapp/blob/production/letstalk-api-openapi.yaml"
    click cognito "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/cognito/"
    click dynamodbScripts "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/dynamodb/"
    click s3scripts "https://github.com/saya-setona/letstalk-webapp/blob/production/aws/s3/create-buckets.sh"
    click shared "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/shared/"
    click deployLambda "https://github.com/saya-setona/letstalk-webapp/blob/production/aws/lambda/deploy-functions.sh"
    click login "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-auth-login/"
    click register "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-auth-register/"
    click refresh "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-auth-refresh/"
    click msgs "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-community-messages/"
    click docs "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-documents/"
    click notes "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-notifications/"
    click sr "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-service-requests/"
    click users "https://github.com/saya-setona/letstalk-webapp/tree/production/aws/lambda/src/letstalk-users/"
    click build "https://github.com/saya-setona/letstalk-webapp/blob/production/package.json"

    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef auth fill:#F3E8FF,stroke:#7E22CE,color:#7E22CE
    classDef api fill:#E0F2FE,stroke:#0284C7,color:#0284C7
    classDef compute fill:#D1FAE5,stroke:#065F46,color:#065F46
    classDef data fill:#FEF3C7,stroke:#D97706,color:#B45309
    classDef storage fill:#FFF7ED,stroke:#C2410C,color:#9A3412
    classDef ci fill:#E5E7EB,stroke:#6B7280,color:#374151
```
