Kiến trúc Backend

1. Tổng quan kiến trúc

Backend NamO Academy Studio là triển khai đa dịch vụ Serverless Framework v4 trên AWS. Các dịch vụ được triển khai độc lập dưới dạng các CloudFormation stack riêng biệt, chia sẻ bảng DynamoDB, bucket S3 và cấu hình Cognito theo quy ước.

Luồng chính:

• Người dùng xác thực qua Amazon Cognito và gọi các endpoint HTTP của API Gateway.
• Luồng tạo ảnh AI là bất đồng bộ: API tạo bản ghi job, gọi worker Lambda và trả về ngay. Client polling trạng thái job theo job_id.
• Ảnh tạo được tải lên S3 và liên kết với thực thể workflow/board trên Firebase cho UI sản phẩm.
• Job thất bại kích hoạt hoàn tiền NamO Point tự động qua DynamoDB Streams.

Region: ap-southeast-1 (Singapore)

5. Điều phối AI và Workflow Routing

Model-to-Service Mapping

6. Dữ liệu & Storage

DynamoDB

S3

Bucket: Media bucket (theo stage)

Paths: uploads/, resized/ (thumbnail, medium, large)

Metadata: Liên kết project, board, workflow cho UI

Firebase

Boards, workflows, board items, workflow results — product hierarchy và UI state. Workflow results lưu image URLs; resizer cập nhật thumbnail/medium/large variants.

Job Metadata

• Jobs lưu status, prompt, model, credits, image URLs, timestamps. Edit jobs gồm mask và mode.

7. Bảo mật và Kiểm soát vận hành

Authentication / Authorization

• Cognito User Pools — JWT trong header Authorization.
• Protected: generation, edit, upload, users, payments. Unprotected: job status (theo ID), download, exchange rate, payment webhook (signature verified).

Quản lý Secrets

• Firebase, Vertex AI, payment provider credentials qua environment và AWS Secrets Manager.

Kiểm soát Usage

• NamO Point: Trừ khi tạo job; hoàn khi job fail qua refundation stream.
• nanobanana-basic: 3 credits mỗi ảnh, chỉ 1K (không giới hạn theo ngày).
• Vertex model gating: nanobanana-2 giới hạn cho admin role.

Logging / Monitoring

Logs được chuyển tới external monitoring. Lambda logs có trong CloudWatch.

8. Triển khai

Stages: dev, prod, live. Mỗi service triển khai như CloudFormation stack riêng.

Cấu hình theo môi trường qua .env.

Runtime

• Node.js trên AWS Lambda
• Region: ap-southeast-1 (Singapore)

9. Độ tin cậy và hành vi sản phẩm

Tất cả thao tác AI đều bất đồng bộ. Client phải poll để biết hoàn thành. Không có queue service rõ ràng; Lambda async invocation cung cấp buffering.

Lambda concurrency do AWS quản lý. Vertex AI: retry khi 429.

Biện pháp bảo vệ:

• NamO Point trừ trước khi invoke; hoàn khi failure.
• Daily limits cho free-tier model.
• Worker timeouts (tối đa 900s) ngăn invocations chạy quá lâu.

Sơ đồ kiến trúc

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              NamO Academy Studio Backend                         │
└─────────────────────────────────────────────────────────────────────────────────┘

  [Client]
      │
      │ JWT (Cognito)
      ▼
  ┌─────────────────┐
  │  API Gateway     │
  └────────┬────────┘
           │
     ┌─────┴─────┬───────────────┬──────────────┐
     ▼           ▼               ▼              ▼
  ┌──────┐  ┌─────────┐    ┌─────────┐   ┌─────────┐
  │users │  │payments │    │uploads  │   │downloads│
  └──────┘  └─────────┘    └────┬────┘   └────┬────┘
                                │             │
                                ▼             ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │  ai-image (Orchestration)                                                      │
  │  • POST /create → create job(s) → invoke vertexGenerate | nanobananaBasicGenerate      │
  │  • POST /edit → create job → invoke vertexEdit                                 │
  │  • POST /camera-sync → create job → invoke vertexCameraSync          │
  │  • GET /job/{id}, /edit-job/{id}, /camera-sync-job/{id} → poll status     │
  └──────────────────────────────┬───────────────────────────────────────────────┘
                                  │ Lambda Invoke (async, Event)
           ┌─────────────────────┼─────────────────────┐
           ▼                     ▼                     ▼
  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────────────┐
  │ vertexGenerate  │   │ vertexEdit       │   │ vertexCameraSync   │
  │ (Vertex AI)     │   │ (Vertex Imagen)  │   │ (Gemini)                │
  └────────┬────────┘   └────────┬─────────┘   └────────────┬────────────┘
           │                     │                         │
           │    ┌─────────────────┘                         │
           │    │                                           │
           ▼    ▼                                           │
  ┌─────────────────┐                                       │
  │ nanobananaBasicGenerate  │  (browser-based worker)                     │
  └────────┬────────┘                                       │
           │                                                 │
           └─────────────────────┬───────────────────────────┘
                                 │
                                 ▼
  ┌─────────────────┐     ┌──────────────┐
  │ Vertex AI /     │     │ uploads      │  presigned URL
  │ Browser worker  │     │ Lambda       │  → S3 PutObject
  └─────────────────┘     └──────┬───────┘
                                 │
                                 ▼
                           ┌──────────┐
                           │ S3       │  uploads/, resized/
                           │ Bucket   │
                           └────┬─────┘
                                │ s3:ObjectCreated
                                ▼
                           ┌──────────┐
                           │ resizer  │  → Firebase board/workflow
                           │ Lambda   │
                           └──────────┘

  ┌─────────────────────────────────────────────────────────────────────────────┐
  │  DynamoDB Streams (Generate, Edit, CameraSync Job tables)                │
  │  status → "failed"  ──────────────────────►  refundation Lambda              │
  │                                            (NamO Point refund)                    │
  └─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────────┐
  │  Storage                                                                    │
  │  • DynamoDB: jobs, usage, users                                           │
  │  • S3: media (uploads/, resized/)                                           │
  │  • Firebase: boards, workflows, board items, workflow results                 │
  └─────────────────────────────────────────────────────────────────────────────┘