# harsh16bhardwaj/nameframe architecture

> Architecture diagram of the GitHub repository harsh16bhardwaj/nameframe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsh16bhardwaj/nameframe
- Repository: https://github.com/harsh16bhardwaj/nameframe

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** monolith that combines the marketing site, authenticated dashboard, and backend APIs in one repository.
   - The system centers on **event-based certificate generation and distribution**: create an event, attach a certificate template, import participants, render personalized certificates, and send/verify them.

2. **Frontend boundaries**
   - `src/app/page.tsx` and the `src/components/landing/*` subtree implement the public landing experience.
   - `src/app/(dashboard)/*` contains the authenticated product UI: dashboard overview, events list, event detail pages, participants, and templates.
   - `src/app/create`, `src/app/contact`, `src/app/pricing`, and `src/app/verify` are additional public-facing pages, while `src/app/download/[eventID]` is a dedicated certificate download experience.

3. **Dashboard as the main operational surface**
   - The dashboard area is split into:
     - a summary/home view with KPI, activity, and recent-event widgets,
     - an events listing page,
     - a per-event detail workspace.
   - The event detail page is the core operator workflow: it combines template preview/editing, participant management, and export/send actions.

4. **Certificate template workflow**
   - Certificate templates are handled as first-class assets.
   - The `CertificateSection` components, `TemplateUploadModal`, `PreviewModal`, and `CertificatePreview` suggest an in-browser editing flow where organizers upload a background image and adjust text placement/style before issuing certificates.
   - The implementation is likely canvas-driven on the client, matching the README’s HTML5 Canvas emphasis.

5. **Participant management workflow**
   - Participants are imported, searched, filtered, paginated, and exported from the event detail area.
   - The `ParticipantImport` component and the API under `src/app/api/events/[eventId]/import-participants` indicate Excel/CSV-style bulk ingestion.
   - `src/app/api/participants/export` supports downstream reporting or offline processing.

6. **Backend API structure**
   - The app uses **route handlers** under `src/app/api/*` as the service boundary.
   - Major API domains are:
     - `events` for CRUD and event-specific operations,
     - `certificate-templates` for template storage/listing and “used template” discovery,
     - `participants` for participant records and export,
     - `send-email` for single and bulk delivery plus retries,
     - `upload` for asset ingestion,
     - `verify/[code]` for certificate verification,
     - `dashboard/stats` for aggregate metrics,
     - `contact` and `feedback` for inbound form submissions.

7. **Persistence layer**
   - Prisma is the database abstraction layer, with schema and migrations under `prisma/`.
   - The migration history shows the data model evolving around:
     - users,
     - events,
     - certificates,
     - participants,
     - certificate templates,
     - font settings,
     - verification data,
     - email retry fields.
   - This implies the database is the source of truth for event state, participant records, issuance/verification metadata, and email delivery status.

8. **Certificate generation and delivery flow**
   - Typical flow:
     1. create or select an event,
     2. upload/select a template,
     3. import participants,
     4. render individualized certificate images,
     5. download or send them by email.
   - The download route `src/app/download/[eventID]` likely packages certificates for an event, while `send-email/single` and `send-email/bulk` handle distribution.
   - `bulk-retry` plus the retry fields in the schema indicate delivery resiliency is part of the backend design.

9. **Verification subsystem**
   - `src/lib/verification.ts` and `src/app/api/verify/[code]` form a certificate verification path.
   - The presence of an admin route `api/admin/add-verification` suggests verification codes or verification records can be created/seeded after issuance, supporting authenticity checks for generated certificates.

10. **User/session and protection boundary**
   - `src/middleware.ts`, `src/components/protectedPage.tsx`, and `src/components/userSync.tsx` imply route protection and some kind of user synchronization/onboarding layer.
   - The app likely distinguishes public marketing pages from authenticated dashboard operations, with middleware enforcing access control at the edge.

11. **Shared UI and presentation system**
   - `src/components/ui/*`, `src/components/layout/Sidebar.tsx`, and various landing components show a shared component library layered on top of Tailwind/shadcn-style primitives.
   - `src/config/theme.ts`, `src/app/globals.css`, and `src/components/ui/CustomStyles.tsx` control global styling and theme behavior across public and dashboard surfaces.

12. **External services and operational concerns**
   - The README references Cloudinary for image management, and the file tree includes upload-related APIs consistent with asset storage integration.
   - Email delivery is a distinct backend concern, with bulk retry handling indicating operational robustness.
   - Although the README mentions Kafka and AI/RAG reporting, the tree here mainly shows the certificate, participant, verification, and email workflow; any AI/reporting capability is not clearly represented in the present source layout.

13. **What to draw in an architecture diagram**
   - A good diagram would show:
     - public marketing pages and authenticated dashboard as two UI entry zones,
     - Next.js route handlers as the application backend,
     - Prisma/database as the persistence core,
     - upload/email/verification as externalized service paths,
     - certificate generation as the central business workflow connecting templates, participants, and delivery.

Main entry points: [`prisma/schema.prisma`](https://github.com/harsh16bhardwaj/nameframe/blob/main/prisma/schema.prisma) (Prisma Schema), [`src/app/api/events`](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/events) (Events API), [`src/app/(dashboard)/events/[eventId]/page.tsx`](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/events/[eventId]/page.tsx) (Event Workspace), [`src/app/(dashboard)/layout.tsx`](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/layout.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui_public["Public UI"]
  node_home_page["Landing<br/>Next.js page<br/>[page.tsx]"]
  node_landing_components["Landing UI<br/>React section set"]
  node_public_pages["Public Pages<br/>Next.js pages"]
end

subgraph group_ui_dashboard["Dashboard UI"]
  node_dashboard_home["Dashboard<br/>Next.js page<br/>[page.tsx]"]
  node_events_list["Events List<br/>Next.js page<br/>[page.tsx]"]
  node_event_workspace["Event Workspace<br/>Next.js page<br/>[page.tsx]"]
  node_template_editor["Template Editor<br/>Client components"]
  node_participants_ui["Participants<br/>Client components"]
  node_dashboard_shell["App Shell<br/>Layout/auth<br/>[layout.tsx]"]
end

subgraph group_api["Route Handlers"]
  node_events_api["Events API<br/>Route handlers"]
  node_templates_api["Templates API<br/>Route handlers"]
  node_participants_api["Participants API<br/>Route handlers"]
  node_import_api["Import API<br/>Route handler<br/>[route.ts]"]
  node_email_api["Email API<br/>Route handlers"]
  node_verify_api["Verify API<br/>Route handler<br/>[route.ts]"]
  node_upload_api["Upload API<br/>Route handler<br/>[route.ts]"]
  node_stats_api["Stats API<br/>Route handler<br/>[route.ts]"]
  node_verification_lib["Verification Logic<br/>[verification.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_schema["Prisma Schema<br/>Data model<br/>[schema.prisma]"]
  node_migrations["Migrations<br/>Schema history"]
end

node_home_page -->|"renders"| node_landing_components
node_home_page -->|"links"| node_public_pages
node_public_pages -.->|"verify"| node_verify_api
node_public_pages -.->|"create/manage"| node_events_api
node_dashboard_shell -->|"wraps"| node_dashboard_home
node_dashboard_shell -->|"wraps"| node_events_list
node_dashboard_shell -->|"wraps"| node_event_workspace
node_dashboard_home -.->|"loads stats"| node_stats_api
node_events_list -.->|"loads events"| node_events_api
node_event_workspace -.->|"updates event"| node_events_api
node_event_workspace -->|"contains"| node_template_editor
node_event_workspace -->|"contains"| node_participants_ui
node_template_editor -.->|"uploads"| node_upload_api
node_template_editor -.->|"saves template"| node_templates_api
node_participants_ui -.->|"imports"| node_import_api
node_participants_ui -.->|"reads/exports"| node_participants_api
node_email_api -.->|"delivers for events"| node_events_api
node_verify_api -.->|"uses"| node_verification_lib
node_verify_api -.->|"reads"| node_prisma_schema
node_events_api -.->|"persists"| node_prisma_schema
node_templates_api -.->|"persists"| node_prisma_schema
node_participants_api -.->|"persists"| node_prisma_schema
node_import_api -.->|"writes"| node_prisma_schema
node_email_api -.->|"updates status"| node_prisma_schema
node_stats_api -.->|"aggregates"| node_prisma_schema
node_migrations -->|"evolves"| node_prisma_schema

click node_home_page "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/page.tsx"
click node_landing_components "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/components/landing"
click node_public_pages "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/create"
click node_dashboard_home "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_events_list "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/events/page.tsx"
click node_event_workspace "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/events/[eventId]/page.tsx"
click node_template_editor "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/(dashboard)/events/[eventId]/components/CertificateSection"
click node_participants_ui "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/(dashboard)/events/[eventId]/components/ParticipantsTable"
click node_dashboard_shell "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/layout.tsx"
click node_events_api "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/events"
click node_templates_api "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/certificate-templates"
click node_participants_api "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/participants"
click node_import_api "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/events/[eventId]/import-participants/route.ts"
click node_email_api "https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/send-email"
click node_verify_api "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/verify/[code]/route.ts"
click node_upload_api "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/upload/route.ts"
click node_stats_api "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/dashboard/stats/route.ts"
click node_prisma_schema "https://github.com/harsh16bhardwaj/nameframe/blob/main/prisma/schema.prisma"
click node_migrations "https://github.com/harsh16bhardwaj/nameframe/tree/main/prisma/migrations"
click node_verification_lib "https://github.com/harsh16bhardwaj/nameframe/blob/main/src/lib/verification.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_home_page,node_landing_components,node_public_pages toneBlue
class node_dashboard_home,node_events_list,node_event_workspace,node_template_editor,node_participants_ui,node_dashboard_shell toneAmber
class node_events_api,node_templates_api,node_participants_api,node_import_api,node_email_api,node_verify_api,node_upload_api,node_stats_api,node_verification_lib toneMint
class node_prisma_schema,node_migrations toneRose
```

## Components

### Public UI

Marketing and public product entry points

- [Landing](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/page.tsx): Next.js page · Public marketing homepage · `src/app/page.tsx`
- [Landing UI](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/components/landing): React section set · Hero, features, FAQ, pricing, testimonials · `src/components/landing`
- [Public Pages](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/create): Next.js pages · Create, contact, pricing, verify, and download entry points · `src/app/create`

### Dashboard UI

Authenticated operational surface

- [Dashboard](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/dashboard/page.tsx): Next.js page · KPI overview and recent activity · `src/app/(dashboard)/dashboard/page.tsx`
- [Events List](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/events/page.tsx): Next.js page · Events browsing and management · `src/app/(dashboard)/events/page.tsx`
- [Event Workspace](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/events/[eventId]/page.tsx): Next.js page · Per-event operator workspace · `src/app/(dashboard)/events/[eventId]/page.tsx`
- [Template Editor](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/(dashboard)/events/[eventId]/components/CertificateSection): Client components · Upload, preview, and text placement controls · `src/app/(dashboard)/events/[eventId]/components/CertificateSection`
- [Participants](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/(dashboard)/events/[eventId]/components/ParticipantsTable): Client components · Search, filter, paginate, and import participants · `src/app/(dashboard)/events/[eventId]/components/ParticipantsTable`
- [App Shell](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/(dashboard)/layout.tsx): Layout/auth · Dashboard layout, sidebar, protected page, and user sync · `src/app/(dashboard)/layout.tsx`

### Route Handlers

Next.js backend endpoints

- [Events API](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/events): Route handlers · Event CRUD and template association · `src/app/api/events`
- [Templates API](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/certificate-templates): Route handlers · Template storage and used-template lookup · `src/app/api/certificate-templates`
- [Participants API](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/participants): Route handlers · Participant records and export · `src/app/api/participants`
- [Import API](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/events/[eventId]/import-participants/route.ts): Route handler · Bulk participant ingestion for an event · `src/app/api/events/[eventId]/import-participants/route.ts`
- [Email API](https://github.com/harsh16bhardwaj/nameframe/tree/main/src/app/api/send-email): Route handlers · Single, bulk, and retry delivery · `src/app/api/send-email`
- [Verify API](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/verify/[code]/route.ts): Route handler · Certificate verification by code · `src/app/api/verify/[code]/route.ts`
- [Upload API](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/upload/route.ts): Route handler · Asset ingestion for templates and images · `src/app/api/upload/route.ts`
- [Stats API](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/app/api/dashboard/stats/route.ts): Route handler · Dashboard aggregates and KPIs · `src/app/api/dashboard/stats/route.ts`
- [Verification Logic](https://github.com/harsh16bhardwaj/nameframe/blob/main/src/lib/verification.ts): Library · Shared verification helpers · `src/lib/verification.ts`

### Persistence

Prisma schema and migrations

- [Prisma Schema](https://github.com/harsh16bhardwaj/nameframe/blob/main/prisma/schema.prisma): Data model · Users, events, certificates, participants, templates, verification, retries · `prisma/schema.prisma`
- [Migrations](https://github.com/harsh16bhardwaj/nameframe/tree/main/prisma/migrations): Schema history · Evolving database structure · `prisma/migrations`

## Connections

- Landing → Landing UI: renders · Homepage composes the landing sections
- Landing → Public Pages: links · Public navigation reaches create, pricing, contact, verify, and download
- Public Pages → Verify API: verify · Public verification page calls the verification endpoint
- Public Pages → Events API: create/manage · Create flow and event-related public actions use the event backend
- App Shell → Dashboard: wraps · Authenticated shell hosts the dashboard overview
- App Shell → Events List: wraps · Authenticated shell hosts the events list
- App Shell → Event Workspace: wraps · Authenticated shell hosts the event workspace
- Dashboard → Stats API: loads stats · KPI cards and activity widgets consume dashboard aggregates
- Events List → Events API: loads events · Events listing reads from the event API
- Event Workspace → Events API: updates event · Workspace edits event metadata and template links
- Event Workspace → Template Editor: contains · Event detail embeds certificate template editing
- Event Workspace → Participants: contains · Event detail embeds participant management
- Template Editor → Upload API: uploads · Template assets are uploaded through the upload endpoint
- Template Editor → Templates API: saves template · Template selection and persistence use template routes
- Participants → Import API: imports · Bulk participant upload uses the event import endpoint
- Participants → Participants API: reads/exports · Participant table loads and exports participant data
- Email API → Events API: delivers for events · Bulk and single sends are coordinated around event records
- Verify API → Verification Logic: uses · Route delegates verification checks to shared logic
- Verify API → Prisma Schema: reads · Verification codes and issuance metadata come from the database
- Events API → Prisma Schema: persists · Events, certificates, and related state are stored via Prisma
- Templates API → Prisma Schema: persists · Template records and usage tracking live in the database
- Participants API → Prisma Schema: persists · Participant records and exports are backed by Prisma models
- Import API → Prisma Schema: writes · Imported participants are stored in the database
- Email API → Prisma Schema: updates status · Retry fields and delivery state are persisted
- Stats API → Prisma Schema: aggregates · Dashboard metrics are computed from persisted data
- Migrations → Prisma Schema: evolves · Migration history defines the schema over time