# ramjit-soren/generative-ai-apps architecture

> Architecture diagram of the GitHub repository ramjit-soren/generative-ai-apps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramjit-soren/generative-ai-apps
- Repository: https://github.com/ramjit-soren/generative-ai-apps

## Overview

1. This repository is a catalog of many independent AI SaaS templates, not a single application. The root `README.md` is the product catalog, and each subfolder under `ai_agents`, `image_generation`, `video_generation`, `beauty_fashion`, `ecommerce`, `home_real_estate`, `portrait_avatar`, `writing_content`, and `platforms` is a standalone deployable product.

2. Most templates share the same SaaS spine: a Next.js App Router frontend in `src/app`, API routes in `src/app/api`, reusable UI in `src/components`, and server-side helpers in `src/lib`. That shared shape is the main architecture pattern across the repo.

3. The typical data boundary is browser → Next.js route handler → service layer → database / external AI provider. The UI pages drive actions like login, pricing, gallery, dashboard, and creation views; the API layer performs auth checks, billing checks, generation requests, and persistence.

4. Persistence is usually Prisma-backed. Each app has its own `prisma/schema.prisma`, a `prisma.config.ts`, and `src/lib/prisma.js`, which means the database model is local to each template rather than shared across the repo. The README confirms PostgreSQL is the standard backing store.

5. Authentication is centralized around NextAuth with a Google OAuth-style login flow. The auth entry point is usually `src/app/api/auth/[...nextauth]/route.js`, supported by `src/lib/auth.js`, and the UI exposes login and protected dashboard/gallery areas.

6. Billing is a first-class subsystem. Templates expose checkout endpoints and Stripe webhook handlers, with billing logic factored into `src/lib/services/billing.js` and Stripe client setup in `src/lib/stripe.js`. The usual flow is: user initiates checkout, Stripe confirms payment, webhook updates account state or credits in the database.

7. AI generation is usually isolated behind feature-specific route handlers and a service wrapper. Common patterns include `/api/generation`, `/api/upload`, `/api/download`, `/api/creations`, plus feature routes such as `/api/headshot`, `/api/logo`, `/api/tryon`, `/api/fitness`, `/api/seedance`, or `/api/generate`. These endpoints typically store a job record, call MuAPI or another model provider, and later return status or artifacts.

8. Many products use asynchronous job polling rather than synchronous generation. Evidence in the tree includes `status` endpoints like `/api/headshot/status`, `/api/generate/status`, `/api/banana/status`, `/api/fitness/status`, and `/api/seedance/check-status`. This suggests a job lifecycle of submit → persist job id → poll status → materialize result in gallery/creations.

9. The UI layer is mostly shared layout plus vertical-specific feature components. Common pieces include `Navbar`, `Footer`, `Providers`, and domain-specific widgets like templates, sliders, forms, editors, selectors, credit badges, and canvas-like views. This keeps the top-level app shell consistent while each niche product swaps in its own generation UX.

10. There are some higher-complexity platform projects that break the usual single-app pattern. `platforms/Open-Generative-AI` adds an Electron shell, local inference modules, and a separate `packages/studio` UI package; `platforms/Open-AI-Design-Agent` and `platforms/Open-Poe-AI` split into a Next.js client plus a Python server; `platforms/Open-Generative-AI` also includes model catalogs, workflow routes, and local model management. These are multi-runtime architectures rather than standard SaaS templates.

11. The main external service boundaries are Stripe for payments, MuAPI for model access and async generation, and Google OAuth through NextAuth. Some niche templates add their own provider-specific routes, but the repo-wide architecture is still built around those three integration points.

12. For an architecture diagram, the key takeaway is that this repo is a factory of self-contained SaaS products with a common reference architecture: Next.js frontend, API routes, Prisma/Postgres, auth, Stripe billing, and AI-job orchestration. The important variation is whether a template stays within that standard stack or adds an extra backend/runtime layer for local inference, desktop packaging, or specialized processing.

Main entry points: [`ai_agents/ai-knowledge-base/src/app`](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app) (App Router), [`README.md`](https://github.com/ramjit-soren/generative-ai-apps/blob/main/README.md) (Catalog README), [`ai_agents/ai-knowledge-base/src/lib`](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/lib) (Service layer), [`ai_agents/ai-knowledge-base/src/app/api`](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app/api) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog"]
  node_readme["Catalog README<br/>product catalog<br/>[README.md]"]
end

subgraph group_shared["Shared stack"]
  node_app_shell["App Router<br/>Next.js app"]
  node_api_routes["API routes<br/>route handlers"]
  node_ui_shell["UI shell<br/>shared components"]
  node_service_layer["Service layer<br/>server helpers"]
  node_db_schema[("Prisma schema<br/>local data model<br/>[schema.prisma]")]
  node_auth_mod["Auth<br/>[auth.js]"]
  node_billing_mod["Billing<br/>[billing.js]"]
  node_stripe_mod["Stripe client<br/>payment client<br/>[stripe.js]"]
  node_ai_service["AI service<br/>generation service<br/>[ai.js]"]
end

subgraph group_templates["Templates"]
  node_family_ai_agents["AI agents<br/>template family"]
  node_family_image_generation["Image generation<br/>template family"]
  node_family_video_generation["Video generation<br/>template family"]
  node_family_beauty_fashion["Beauty/fashion<br/>template family"]
  node_family_ecommerce["Ecommerce<br/>template family"]
  node_family_home_real_estate["Real estate<br/>template family"]
  node_family_portrait_avatar["Portrait/avatar<br/>template family"]
  node_family_writing_content["Writing/content<br/>template family"]
end

subgraph group_platforms["Platforms"]
  node_family_platforms["Platforms<br/>platform family"]
  node_python_sidecar["Python server<br/>aux runtime"]
  node_electron_shell["Electron shell<br/>desktop runtime"]
  node_studio_pkg["Studio UI<br/>shared package"]
end

subgraph group_integrations["Integrations"]
  node_postgres[("Postgres<br/>database")]
  node_nextauth(("Google OAuth<br/>identity provider"))
  node_stripe(("Stripe<br/>payments"))
  node_muapi(("MuAPI<br/>model provider"))
end

node_readme -->|"indexes"| node_family_ai_agents
node_readme -->|"indexes"| node_family_image_generation
node_readme -->|"indexes"| node_family_video_generation
node_readme -->|"indexes"| node_family_beauty_fashion
node_readme -->|"indexes"| node_family_ecommerce
node_readme -->|"indexes"| node_family_home_real_estate
node_readme -->|"indexes"| node_family_portrait_avatar
node_readme -->|"indexes"| node_family_writing_content
node_readme -->|"indexes"| node_family_platforms
node_family_ai_agents -->|"contains"| node_app_shell
node_family_image_generation -->|"contains"| node_app_shell
node_family_video_generation -->|"contains"| node_app_shell
node_family_beauty_fashion -->|"contains"| node_app_shell
node_family_ecommerce -->|"contains"| node_app_shell
node_family_home_real_estate -->|"contains"| node_app_shell
node_family_portrait_avatar -->|"contains"| node_app_shell
node_family_writing_content -->|"contains"| node_app_shell
node_family_platforms -->|"may add"| node_python_sidecar
node_family_platforms -->|"may add"| node_electron_shell
node_family_platforms -->|"may add"| node_studio_pkg
node_app_shell -->|"routes through"| node_api_routes
node_app_shell -->|"renders with"| node_ui_shell
node_api_routes -->|"uses"| node_auth_mod
node_api_routes -->|"uses"| node_billing_mod
node_api_routes -->|"uses"| node_ai_service
node_service_layer -->|"contains"| node_auth_mod
node_service_layer -->|"contains"| node_billing_mod
node_service_layer -->|"contains"| node_ai_service
node_service_layer -->|"contains"| node_stripe_mod
node_service_layer -->|"persists via"| node_db_schema
node_auth_mod -->|"delegates to"| node_nextauth
node_billing_mod -->|"delegates to"| node_stripe
node_stripe_mod -->|"connects to"| node_stripe
node_ai_service -->|"delegates to"| node_muapi
node_db_schema -->|"targets"| node_postgres
node_api_routes -->|"writes"| node_db_schema
node_ui_shell -->|"supports"| node_app_shell
node_python_sidecar -->|"calls"| node_muapi
node_electron_shell -->|"hosts"| node_studio_pkg
node_electron_shell -->|"calls"| node_muapi

click node_readme "https://github.com/ramjit-soren/generative-ai-apps/blob/main/README.md"
click node_family_ai_agents "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents"
click node_family_image_generation "https://github.com/ramjit-soren/generative-ai-apps/tree/main/image_generation"
click node_family_video_generation "https://github.com/ramjit-soren/generative-ai-apps/tree/main/video_generation"
click node_family_beauty_fashion "https://github.com/ramjit-soren/generative-ai-apps/tree/main/beauty_fashion"
click node_family_ecommerce "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ecommerce"
click node_family_home_real_estate "https://github.com/ramjit-soren/generative-ai-apps/tree/main/home_real_estate"
click node_family_portrait_avatar "https://github.com/ramjit-soren/generative-ai-apps/tree/main/portrait_avatar"
click node_family_writing_content "https://github.com/ramjit-soren/generative-ai-apps/tree/main/writing_content"
click node_family_platforms "https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms"
click node_app_shell "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app"
click node_api_routes "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app/api"
click node_ui_shell "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/components"
click node_service_layer "https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/lib"
click node_db_schema "https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/prisma/schema.prisma"
click node_auth_mod "https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/auth.js"
click node_billing_mod "https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/services/billing.js"
click node_stripe_mod "https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/stripe.js"
click node_ai_service "https://github.com/ramjit-soren/generative-ai-apps/blob/main/image_generation/ai-headshot-generator/src/lib/services/ai.js"
click node_python_sidecar "https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-AI-Design-Agent/server"
click node_electron_shell "https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-Generative-AI/electron"
click node_studio_pkg "https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-Generative-AI/packages/studio"

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_readme toneBlue
class node_app_shell,node_api_routes,node_ui_shell,node_service_layer,node_db_schema,node_auth_mod,node_billing_mod,node_stripe_mod,node_ai_service toneAmber
class node_family_ai_agents,node_family_image_generation,node_family_video_generation,node_family_beauty_fashion,node_family_ecommerce,node_family_home_real_estate,node_family_portrait_avatar,node_family_writing_content toneMint
class node_family_platforms,node_python_sidecar,node_electron_shell,node_studio_pkg toneRose
class node_postgres,node_nextauth,node_stripe,node_muapi toneIndigo
```

## Components

### Catalog

Repository-level index of template families

- [Catalog README](https://github.com/ramjit-soren/generative-ai-apps/blob/main/README.md): product catalog · Root README that explains the template factory and shared SaaS pattern · `README.md`

### Shared stack

Common SaaS architecture reused by most templates

- [App Router](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app): Next.js app · Browser-facing pages and application shell, typically under src/app · `ai_agents/ai-knowledge-base/src/app`
- [API routes](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/app/api): route handlers · Auth, billing, generation, upload, download, and webhook handlers · `ai_agents/ai-knowledge-base/src/app/api`
- [UI shell](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/components): shared components · Common navbar, footer, provider, and domain widgets · `ai_agents/ai-knowledge-base/src/components`
- [Service layer](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents/ai-knowledge-base/src/lib): server helpers · Auth, billing, AI, user, and provider helper modules · `ai_agents/ai-knowledge-base/src/lib`
- [Prisma schema](https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/prisma/schema.prisma): local data model · Per-template database schema and Prisma config · `ai_agents/ai-knowledge-base/prisma/schema.prisma`
- [Auth](https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/auth.js): NextAuth helper · NextAuth entry and auth helper for OAuth-style login · `ai_agents/ai-knowledge-base/src/lib/auth.js`
- [Billing](https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/services/billing.js): billing service · Checkout and account-state logic for Stripe monetization · `ai_agents/ai-knowledge-base/src/lib/services/billing.js`
- [Stripe client](https://github.com/ramjit-soren/generative-ai-apps/blob/main/ai_agents/ai-knowledge-base/src/lib/stripe.js): payment client · Stripe SDK setup used by checkout and webhook handlers · `ai_agents/ai-knowledge-base/src/lib/stripe.js`
- [AI service](https://github.com/ramjit-soren/generative-ai-apps/blob/main/image_generation/ai-headshot-generator/src/lib/services/ai.js): generation service · Wrapper around MuAPI or other model providers for generation jobs · `image_generation/ai-headshot-generator/src/lib/services/ai.js`

### Templates

Standalone product families

- [AI agents](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ai_agents): template family · Standalone agent-oriented templates and adjacent apps · `ai_agents`
- [Image generation](https://github.com/ramjit-soren/generative-ai-apps/tree/main/image_generation): template family · Standalone image-focused SaaS templates · `image_generation`
- [Video generation](https://github.com/ramjit-soren/generative-ai-apps/tree/main/video_generation): template family · Standalone video-focused SaaS templates and pipelines · `video_generation`
- [Beauty/fashion](https://github.com/ramjit-soren/generative-ai-apps/tree/main/beauty_fashion): template family · Standalone vertical SaaS templates for beauty and fashion workflows · `beauty_fashion`
- [Ecommerce](https://github.com/ramjit-soren/generative-ai-apps/tree/main/ecommerce): template family · Standalone commerce-oriented product studios · `ecommerce`
- [Real estate](https://github.com/ramjit-soren/generative-ai-apps/tree/main/home_real_estate): template family · Standalone home and property workflow templates · `home_real_estate`
- [Portrait/avatar](https://github.com/ramjit-soren/generative-ai-apps/tree/main/portrait_avatar): template family · Standalone portrait, avatar, and identity templates · `portrait_avatar`
- [Writing/content](https://github.com/ramjit-soren/generative-ai-apps/tree/main/writing_content): template family · Standalone writing and content-generation templates · `writing_content`

### Platforms

Multi-runtime projects with extra backends or desktop layers

- [Platforms](https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms): platform family · Higher-complexity products with extra runtimes or packaging layers · `platforms`
- [Python server](https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-AI-Design-Agent/server): aux runtime · Supplementary backend runtime used by some platform projects · `platforms/Open-AI-Design-Agent/server`
- [Electron shell](https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-Generative-AI/electron): desktop runtime · Desktop packaging and local inference runtime for Open-Generative-AI · `platforms/Open-Generative-AI/electron`
- [Studio UI](https://github.com/ramjit-soren/generative-ai-apps/tree/main/platforms/Open-Generative-AI/packages/studio): shared package · Separate studio package used by multi-package platform projects · `platforms/Open-Generative-AI/packages/studio`

### Integrations

External service boundaries

- **Postgres**: database · Standard persistence backend described by the repo README
- **Google OAuth**: identity provider · External login boundary used through NextAuth
- **Stripe**: payments · External billing and webhook provider
- **MuAPI**: model provider · External AI provider used for async generation and webhooks

## Connections

- Catalog README → AI agents: indexes · Catalog lists this family
- Catalog README → Image generation: indexes · Catalog lists this family
- Catalog README → Video generation: indexes · Catalog lists this family
- Catalog README → Beauty/fashion: indexes · Catalog lists this family
- Catalog README → Ecommerce: indexes · Catalog lists this family
- Catalog README → Real estate: indexes · Catalog lists this family
- Catalog README → Portrait/avatar: indexes · Catalog lists this family
- Catalog README → Writing/content: indexes · Catalog lists this family
- Catalog README → Platforms: indexes · Catalog lists this family
- AI agents → App Router: contains · Typical template shape
- Image generation → App Router: contains · Typical template shape
- Video generation → App Router: contains · Typical template shape
- Beauty/fashion → App Router: contains · Typical template shape
- Ecommerce → App Router: contains · Typical template shape
- Real estate → App Router: contains · Typical template shape
- Portrait/avatar → App Router: contains · Typical template shape
- Writing/content → App Router: contains · Typical template shape
- Platforms → Python server: may add · Some platform projects split into a separate Python backend
- Platforms → Electron shell: may add · Open-Generative-AI adds a desktop runtime
- Platforms → Studio UI: may add · Open-Generative-AI uses a separate studio package
- App Router → API routes: routes through · Browser actions are handled through route handlers
- App Router → UI shell: renders with · Pages share a common app shell and reusable widgets
- API routes → Auth: uses · Authentication endpoints and guards
- API routes → Billing: uses · Checkout and webhook handling
- API routes → AI service: uses · Generation and async job orchestration
- Service layer → Auth: contains · Auth helper lives in the service boundary
- Service layer → Billing: contains · Billing helper lives in the service boundary
- Service layer → AI service: contains · AI helper lives in the service boundary
- Service layer → Stripe client: contains · Stripe client setup lives in the service boundary
- Service layer → Prisma schema: persists via · Local Prisma schema defines the backing store
- Auth → Google OAuth: delegates to · NextAuth wraps the external login flow
- Billing → Stripe: delegates to · Billing depends on Stripe checkout and webhooks
- Stripe client → Stripe: connects to · Stripe SDK boundary
- AI service → MuAPI: delegates to · Primary model provider boundary
- Prisma schema → Postgres: targets · Standard persistence backend
- API routes → Prisma schema: writes · Handlers store jobs, credits, and artifacts locally
- UI shell → App Router: supports · Shared UI components feed the pages
- Python server → MuAPI: calls · Design-agent sidecar uses MuAPI helpers
- Electron shell → Studio UI: hosts · Desktop app embeds the studio UI package
- Electron shell → MuAPI: calls · Local inference and cloud provider boundary