# vietductran16092003/fpt-avatar-frame-platform- architecture

> Architecture diagram of the GitHub repository vietductran16092003/fpt-avatar-frame-platform-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vietductran16092003/fpt-avatar-frame-platform-
- Repository: https://github.com/vietductran16092003/fpt-avatar-frame-platform-

## Overview

FPT Avatar Frame Platform lets employees browse active campaigns, personalize a frame with a photo and overlay values, then generate and download an avatar; optional sign-in exposes download history. Admins manage campaigns and templates, review notifications, and inspect analytics. The graph reflects the documented product capabilities and sampled API ownership; several UI, auth, and analytics implementations were not sampled, so uncertain wiring is omitted.

Main entry points: [`src/app/api/campaigns/[slug]/generate/route.ts`](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/%5Bslug%5D/generate/route.ts) (Avatar generation API), [`src/lib/server/prisma.ts`](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/prisma.ts) (PostgreSQL data), [`src/app/(public)/c/[slug]/avatar-creator.tsx`](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/c/%5Bslug%5D/avatar-creator.tsx) (Avatar creator), [`src/app/admin/campaigns/page.tsx`](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/admin/campaigns/page.tsx) (Campaign admin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public experience"]
  node_public_site["Campaign browsing<br/>[page.tsx]"]
  node_campaign_cards["Campaign cards<br/>[campaign-cards.tsx]"]
  node_campaign_creator["Avatar creator<br/>[avatar-creator.tsx]"]
  node_canvas_preview["Canvas preview"]
  node_account_history["Download history"]
  node_history_api["Account history page<br/>[page.tsx]"]
end

subgraph group_generation["Avatar generation"]
  node_campaign_api["Public campaign APIs<br/>[route.ts]"]
  node_campaign_detail_api["Campaign detail API<br/>[route.ts]"]
  node_generate_api["Avatar generation API<br/>[route.ts]"]
  node_overlay_validation["Overlay validation"]
  node_compositor["Server compositor"]
  node_placement["Photo placement<br/>[photo-placement.ts]"]
end

subgraph group_admin["Admin operations"]
  node_admin_pages["Campaign admin<br/>[page.tsx]"]
  node_admin_campaign_api["Campaign admin APIs<br/>[route.ts]"]
  node_template_api["Template admin API<br/>[route.ts]"]
  node_notifications_api["Notification APIs<br/>[route.ts]"]
  node_analytics_page["Analytics dashboard<br/>[page.tsx]"]
  node_analytics_api["Analytics API<br/>[route.ts]"]
end

subgraph group_identity["Identity"]
  node_auth_api["Authentication API<br/>[route.ts]"]
  node_session["Session access<br/>[session.ts]"]
end

subgraph group_platform["Data and integrations"]
  node_notification_service["Notification service<br/>[notifications.ts]"]
  node_ga_report["GA4 reporting<br/>[ga4-report.ts]"]
  node_ga_events["GA4 event client<br/>[ga4-client.ts]"]
  node_prisma[("PostgreSQL data<br/>[prisma.ts]")]
  node_storage["Image storage adapter<br/>[index.ts]"]
end

node_employee(("Employee"))
node_administrator(("Administrator"))
node_minio[("MinIO object storage")]
node_ga4["Google Analytics 4"]

node_employee -->|"browses"| node_public_site
node_public_site -->|"shows"| node_campaign_cards
node_campaign_cards -->|"requests campaigns"| node_campaign_api
node_employee -->|"personalizes"| node_campaign_creator
node_campaign_creator -->|"loads campaign"| node_campaign_detail_api
node_campaign_creator -->|"previews photo"| node_canvas_preview
node_canvas_preview -->|"uses transform"| node_placement
node_campaign_creator -->|"submits avatar"| node_generate_api
node_generate_api -->|"gets user"| node_session
node_generate_api -->|"reads campaign and template"| node_prisma
node_generate_api -->|"validates values"| node_overlay_validation
node_generate_api -->|"clamps transform"| node_placement
node_generate_api -->|"loads frame, saves result"| node_storage
node_generate_api -->|"renders avatar"| node_compositor
node_generate_api -->|"records generation"| node_prisma
node_generate_api -->|"creates notice"| node_notification_service
node_storage -->|"stores images"| node_minio
node_employee -.->|"signs in"| node_auth_api
node_auth_api -.->|"persists user"| node_prisma
node_employee -.->|"views history"| node_history_api
node_history_api -->|"renders"| node_account_history
node_administrator -->|"manages campaigns"| node_admin_pages
node_admin_pages -->|"requests campaign changes"| node_admin_campaign_api
node_admin_pages -->|"manages templates"| node_template_api
node_admin_campaign_api -->|"reads and writes campaigns"| node_prisma
node_template_api -->|"uploads frame"| node_storage
node_template_api -->|"writes template"| node_prisma
node_admin_campaign_api -->|"creates notices"| node_notification_service
node_administrator -->|"reviews notices"| node_notifications_api
node_notifications_api -->|"reads and deletes notices"| node_prisma
node_notification_service -->|"writes notice"| node_prisma
node_administrator -->|"views metrics"| node_analytics_page
node_analytics_page -->|"requests report"| node_analytics_api
node_analytics_api -->|"queries generation data"| node_prisma
node_analytics_api -->|"fetches field report"| node_ga_report
node_ga_report -.->|"queries reports"| node_ga4
node_campaign_creator -.->|"tracks activity"| node_ga_events
node_ga_events -.->|"sends events"| node_ga4

click node_public_site "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/page.tsx"
click node_campaign_cards "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/campaign-cards.tsx"
click node_campaign_creator "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/c/%5Bslug%5D/avatar-creator.tsx"
click node_canvas_preview "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/c/%5Bslug%5D/use-avatar-canvas.ts"
click node_account_history "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/tai-khoan/account-history.tsx"
click node_campaign_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/route.ts"
click node_campaign_detail_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/%5Bslug%5D/route.ts"
click node_generate_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/%5Bslug%5D/generate/route.ts"
click node_overlay_validation "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/compositing/validate-overlay-values.ts"
click node_compositor "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/compositing/server-compositor.ts"
click node_placement "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/compositing/photo-placement.ts"
click node_admin_pages "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/admin/campaigns/page.tsx"
click node_admin_campaign_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/campaigns/route.ts"
click node_template_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/campaigns/%5Bslug%5D/templates/route.ts"
click node_notifications_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/notifications/route.ts"
click node_notification_service "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/notifications.ts"
click node_analytics_page "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/admin/analytics/page.tsx"
click node_analytics_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/analytics/route.ts"
click node_ga_report "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/analytics/ga4-report.ts"
click node_ga_events "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/analytics/ga4-client.ts"
click node_auth_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts"
click node_session "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/session.ts"
click node_history_api "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/tai-khoan/page.tsx"
click node_prisma "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/prisma.ts"
click node_storage "https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/storage/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_site,node_campaign_cards,node_campaign_creator,node_canvas_preview,node_account_history,node_history_api toneBlue
class node_campaign_api,node_campaign_detail_api,node_generate_api,node_overlay_validation,node_compositor,node_placement,node_minio toneAmber
class node_admin_pages,node_admin_campaign_api,node_template_api,node_notifications_api,node_analytics_page,node_analytics_api toneMint
class node_auth_api,node_session toneRose
class node_notification_service,node_ga_report,node_ga_events,node_prisma,node_storage,node_employee,node_administrator,node_ga4 toneIndigo
```

## Components

### Public experience

- [Campaign browsing](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/page.tsx): `src/app/(public)/page.tsx`
- [Campaign cards](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/campaign-cards.tsx): `src/app/(public)/campaign-cards.tsx`
- [Avatar creator](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/c/%5Bslug%5D/avatar-creator.tsx): `src/app/(public)/c/[slug]/avatar-creator.tsx`
- [Canvas preview](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/c/%5Bslug%5D/use-avatar-canvas.ts): `src/app/(public)/c/[slug]/use-avatar-canvas.ts`
- [Download history](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/tai-khoan/account-history.tsx): `src/app/(public)/tai-khoan/account-history.tsx`
- [Account history page](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/(public)/tai-khoan/page.tsx): `src/app/(public)/tai-khoan/page.tsx`

### Avatar generation

- [Public campaign APIs](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/route.ts): `src/app/api/campaigns/route.ts`
- [Campaign detail API](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/%5Bslug%5D/route.ts): `src/app/api/campaigns/[slug]/route.ts`
- [Avatar generation API](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/campaigns/%5Bslug%5D/generate/route.ts): `src/app/api/campaigns/[slug]/generate/route.ts`
- [Overlay validation](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/compositing/validate-overlay-values.ts): `src/lib/server/compositing/validate-overlay-values.ts`
- [Server compositor](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/compositing/server-compositor.ts): `src/lib/server/compositing/server-compositor.ts`
- [Photo placement](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/compositing/photo-placement.ts): `src/lib/compositing/photo-placement.ts`

### Admin operations

- [Campaign admin](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/admin/campaigns/page.tsx): `src/app/admin/campaigns/page.tsx`
- [Campaign admin APIs](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/campaigns/route.ts): `src/app/api/admin/campaigns/route.ts`
- [Template admin API](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/campaigns/%5Bslug%5D/templates/route.ts): `src/app/api/admin/campaigns/[slug]/templates/route.ts`
- [Notification APIs](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/notifications/route.ts): `src/app/api/admin/notifications/route.ts`
- [Analytics dashboard](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/admin/analytics/page.tsx): `src/app/admin/analytics/page.tsx`
- [Analytics API](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/admin/analytics/route.ts): `src/app/api/admin/analytics/route.ts`

### Identity

- [Authentication API](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts): `src/app/api/auth/[...nextauth]/route.ts`
- [Session access](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/session.ts): `src/lib/server/session.ts`

### Data and integrations

- [Notification service](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/notifications.ts): `src/lib/server/notifications.ts`
- [GA4 reporting](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/analytics/ga4-report.ts): `src/lib/server/analytics/ga4-report.ts`
- [GA4 event client](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/analytics/ga4-client.ts): `src/lib/analytics/ga4-client.ts`
- [PostgreSQL data](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/prisma.ts): `src/lib/server/prisma.ts`
- [Image storage adapter](https://github.com/vietductran16092003/fpt-avatar-frame-platform-/blob/main/src/lib/server/storage/index.ts): `src/lib/server/storage/index.ts`

### Other components

- **Employee**
- **Administrator**
- **MinIO object storage**
- **Google Analytics 4**

## Connections

- Employee → Campaign browsing: browses
- Campaign browsing → Campaign cards: shows
- Campaign cards → Public campaign APIs: requests campaigns
- Employee → Avatar creator: personalizes
- Avatar creator → Campaign detail API: loads campaign
- Avatar creator → Canvas preview: previews photo
- Canvas preview → Photo placement: uses transform
- Avatar creator → Avatar generation API: submits avatar
- Avatar generation API → Session access: gets user
- Avatar generation API → PostgreSQL data: reads campaign and template
- Avatar generation API → Overlay validation: validates values
- Avatar generation API → Photo placement: clamps transform
- Avatar generation API → Image storage adapter: loads frame, saves result
- Avatar generation API → Server compositor: renders avatar
- Avatar generation API → PostgreSQL data: records generation
- Avatar generation API → Notification service: creates notice
- Image storage adapter → MinIO object storage: stores images
- Employee → Authentication API: signs in
- Authentication API → PostgreSQL data: persists user
- Employee → Account history page: views history
- Account history page → Download history: renders
- Administrator → Campaign admin: manages campaigns
- Campaign admin → Campaign admin APIs: requests campaign changes
- Campaign admin → Template admin API: manages templates
- Campaign admin APIs → PostgreSQL data: reads and writes campaigns
- Template admin API → Image storage adapter: uploads frame
- Template admin API → PostgreSQL data: writes template
- Campaign admin APIs → Notification service: creates notices
- Administrator → Notification APIs: reviews notices
- Notification APIs → PostgreSQL data: reads and deletes notices
- Notification service → PostgreSQL data: writes notice
- Administrator → Analytics dashboard: views metrics
- Analytics dashboard → Analytics API: requests report
- Analytics API → PostgreSQL data: queries generation data
- Analytics API → GA4 reporting: fetches field report
- GA4 reporting → Google Analytics 4: queries reports
- Avatar creator → GA4 event client: tracks activity
- GA4 event client → Google Analytics 4: sends events