1. Architecture Overview
The NamO Academy Studio backend is a multi-service Serverless Framework v4 deployment on AWS. Services are deployed independently as separate CloudFormation stacks, sharing DynamoDB tables, S3 buckets, and Cognito configuration by convention.
High-level flow:
- Users authenticate via Amazon Cognito and call API Gateway HTTP endpoints.
- AI generation flows are asynchronous: the API creates a job record, invokes a worker Lambda, and returns immediately. The client polls job status by job_id.
- Generated images are uploaded to S3 and linked to Firebase workflow/board entities for the product UI.
- Failed jobs trigger automatic NamO Point refunds via DynamoDB Streams.
Region: ap-southeast-1 (Singapore)
2. Core Backend Components
| Component | Technology | Purpose |
|---|---|---|
| API layer | API Gateway + Lambda | HTTP endpoints for create, edit, camera-sync, job status, upload presigned URL |
| AI workers | Lambda (vertex) | Long-running image generation (Vertex AI) |
| Orchestration | ai-image service | Validates requests, reserves entitlements, creates jobs, invokes workers via Lambda async |
| Queue / async | Lambda InvocationType: Event | Fire-and-forget invocation of worker Lambdas (no SQS) |
| Storage | DynamoDB, S3, Firebase | Jobs, usage, users, keys; media in S3; boards/workflows in Firebase |
| Refund processor | Lambda (DynamoDB Streams) | Refunds credits when job status transitions to failed |
| Image processing | Lambda (S3 trigger) | Resizer processes uploads, creates thumbnail/medium/large variants |
3. Request Flow
3.1 Image Generation
- User submits generation request; API validates, checks entitlement (credits or daily limit).
- API creates job(s) in database, invokes worker Lambda asynchronously, returns job ID(s) immediately.
- Client polls for status (pending → processing → completed | failed).
- Worker calls AI provider (Vertex AI or a browser-based worker), uploads result to S3, updates workflow in Firebase.
- Resizer creates thumbnail/medium/large variants; client receives completed status and image URLs.
3.2 Image Edit & Texture Transfer
- Same async pattern: API creates job, invokes worker, returns job ID.
- Client polls; worker uses Vertex Imagen (edit) or Gemini (camera sync), uploads to S3, updates Firebase.
3.3 Upload
- Client requests presigned URL; uploads directly to S3.
- S3 trigger runs resizer; resizer updates Firebase with resized URLs.
4. Services Overview
ai-image
Orchestrates generation, edit, camera-sync; validates requests, creates jobs, invokes workers
vertex
Vertex AI image generation, edit (inpaint/outpaint), camera sync
uploads
Presigned S3 URLs; resizer creates thumbnail/medium/large variants
downloads
Short-lived presigned download URLs
users
User CRUD, usage, Cognito sync
payments
Payment links, webhook, exchange rate
refundation
Automatic NamO Point refund when jobs fail (DynamoDB Streams)
5. AI Orchestration and Workflow Routing
Model-to-Service Mapping
| Model | Worker | Provider | NamO Point |
|---|---|---|---|
| nanobanana-basic | nanobananaBasicGenerate | browser-based worker | 2 per image (1K only) |
| nanobanana-pro | vertexGenerate | Vertex AI — Gemini 3.0 Pro Image Preview (gemini-3.0-pro-image-preview) | 1 per image |
| nanobanana-2 | vertexGenerate / vertexEdit / vertexCameraSync | Vertex AI — Gemini 3.1 Flash Image Preview (gemini-3.1-flash-image-preview) for generate/texture-transfer; Imagen 3.0 (imagen-3.0-capability-001) for edit | 1 per image |
Vertex AI models in use
- vertexGenerate → Gemini 3.1 Pro Preview (gemini-3.1-pro-preview)
- vertexEdit → Imagen 3.0 (imagen-3.0-capability-001)
- vertexTextureTransfer → Gemini 3.1 Pro Preview (gemini-3.1-pro-preview)
Failure and Retry Handling
- Vertex AI: Exponential backoff retry (up to 5 retries) for 429, 5xx, timeout, network errors.
- Job failure: Worker sets job status to failed with error_message; refundation stream refunds credits.
6. Data & Storage
DynamoDB
| Table | Service | Purpose |
|---|---|---|
| Jobs | ai-image | Generation, edit, camera-sync jobs; streams for refunds |
| Usage | ai-image | Per-user daily limits |
| Users | users | Profile, credits, role |
| Payments | payments | Payment records, exchange rates |
S3
Bucket: Media bucket (per stage)
Paths: uploads/, resized/ (thumbnail, medium, large)
Metadata: Linked to project, board, workflow for UI
Firebase
Boards, workflows, board items, workflow results — product hierarchy and UI state. Workflow results store image URLs; resizer updates with thumbnail/medium/large variants.
Job Metadata
- Jobs store status, prompt, model, credits, image URLs, timestamps. Edit jobs include mask and mode.
7. Security and Operational Controls
Authentication / Authorization
- Cognito User Pools — JWT in Authorization header.
- Protected: generation, edit, upload, users, payments. Unprotected: job status (by ID), download, exchange rate, payment webhook (signature verified).
Secrets Management
- Firebase, Vertex AI, payment provider credentials via environment and AWS Secrets Manager.
Usage Controls
- NamO Point: Deducted at job creation; refunded on job failure by refundation stream.
- nanobanana-basic: 3 credits per image, 1K only (no daily limit).
- Vertex model gating: nanobanana-2 restricted to admin role.
Logging / Monitoring
Logs available in CloudWatch; forwarded to external monitoring.
8. Deployment
Stages: dev, prod, live. Each service deploys as a separate CloudFormation stack.
Environment-specific configuration via .env.
Runtime
- Node.js on AWS Lambda
- Region: ap-southeast-1 (Singapore)
9. Reliability and Product Behavior
| State | Backend behavior | User experience |
|---|---|---|
| Queued | Job created, worker invoked | Immediate response with job_id |
| Processing | Worker running, status updated | Poll returns processing |
| Completed | Job and workflow result updated, resizer triggered | Poll returns completed, image URLs available |
| Failed | Job status set, credits refunded | Poll returns failed, error_message shown |
All AI operations are asynchronous. Client must poll for completion. No explicit queue service; Lambda async invocation provides buffering.
Lambda concurrency is managed by AWS. Vertex AI: retries on 429.
Safeguards:
- NamO Point deducted before invocation; refund on failure.
- Daily limits for free-tier model.
- Worker timeouts (up to 900s) prevent runaway invocations.
Architecture Diagram
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────────────────┘