# seoynbnexus/flowx architecture

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

- Interactive diagram: https://gitdiagram.com/seoynbnexus/flowx
- Repository: https://github.com/seoynbnexus/flowx

## Overview

Flowx is a social-advertising and creator-campaign platform with account management, AI-assisted content, media and post workflows, campaign execution, and monetization. The principal user journey spans account access, preparing content or a campaign, connecting social accounts, and managing payments or usage. The tree identifies these product areas, while sampled excerpts confirm selected service calls and persistence; unsampled module wiring is therefore shown only where supported by the available evidence.

Main entry points: [`shared/database/connection.js`](https://github.com/seoynbnexus/flowx/blob/main/shared/database/connection.js) (MySQL database), [`src/modules/auth/auth.service.js`](https://github.com/seoynbnexus/flowx/blob/main/src/modules/auth/auth.service.js) (Authentication), [`src/modules/ai/ai.service.js`](https://github.com/seoynbnexus/flowx/blob/main/src/modules/ai/ai.service.js) (AI generation), [`src/modules/publisher-platforms/oauth.service.js`](https://github.com/seoynbnexus/flowx/blob/main/src/modules/publisher-platforms/oauth.service.js) (Social account linking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts &amp; access"]
  node_auth["Authentication<br/>[auth.service.js]"]
  node_users["User accounts<br/>[user.service.js]"]
  node_permissions["Roles &amp; permissions"]
end

subgraph group_content["Content &amp; AI"]
  node_ai["AI generation<br/>[ai.service.js]"]
  node_moderation["AI moderation"]
  node_media["Media library<br/>[media.service.js]"]
  node_posts["Posts &amp; promotions<br/>[post.service.js]"]
end

subgraph group_campaigns["Campaign operations"]
  node_oauth["Social account linking<br/>[oauth.service.js]"]
  node_campaign["Campaign management"]
  node_execution["Campaign execution"]
  node_webhooks["Meta webhooks"]
end

subgraph group_monetization["Payments &amp; usage"]
  node_payments["Payments<br/>[payment.service.js]"]
  node_subscriptions["Subscriptions &amp; plans"]
  node_ledger["Usage ledger"]
end

subgraph group_platform["Runtime &amp; integrations"]
  node_app["Express application<br/>[app.js]"]
  node_routes["API routes<br/>[index.js]"]
  node_meta_auth["Meta OAuth"]
  node_meta_graph["Meta Graph API"]
  node_ai_provider["AI providers<br/>[provider.js]"]
  node_jobs["Background jobs<br/>[worker.js]"]
  node_razorpay["Razorpay<br/>[razorpay.client.js]"]
  node_analytics["Analytics dashboard"]
  node_database[("MySQL database<br/>[connection.js]")]
end

node_user(("Client or admin"))

node_user -->|"sends requests"| node_app
node_app -->|"dispatches routes"| node_routes
node_auth -->|"reads and writes"| node_database
node_auth -->|"creates accounts"| node_users
node_auth -->|"stores sessions"| node_database
node_oauth -->|"builds auth URL"| node_meta_auth
node_oauth -->|"fetches pages"| node_meta_graph
node_oauth -->|"stores linked accounts"| node_database
node_ai -->|"requests generation"| node_ai_provider
node_ai -->|"checks content"| node_moderation
node_ai -->|"records usage"| node_database
node_media -->|"stores media records"| node_database
node_posts -->|"persists posts"| node_database
node_campaign -->|"persists campaigns"| node_database
node_execution -->|"publishes campaign data"| node_meta_graph
node_webhooks -->|"records webhook events"| node_database
node_jobs -->|"runs scheduled work"| node_execution
node_payments -->|"creates and verifies orders"| node_razorpay
node_payments -->|"records payments"| node_database
node_subscriptions -->|"reads and writes plans"| node_database
node_ledger -->|"records usage"| node_database
node_analytics -->|"queries metrics"| node_database

click node_app "https://github.com/seoynbnexus/flowx/blob/main/app.js"
click node_routes "https://github.com/seoynbnexus/flowx/blob/main/src/routes/index.js"
click node_auth "https://github.com/seoynbnexus/flowx/blob/main/src/modules/auth/auth.service.js"
click node_users "https://github.com/seoynbnexus/flowx/blob/main/src/modules/users/user.service.js"
click node_permissions "https://github.com/seoynbnexus/flowx/blob/main/src/modules/permissions/permission.service.js"
click node_oauth "https://github.com/seoynbnexus/flowx/blob/main/src/modules/publisher-platforms/oauth.service.js"
click node_meta_auth "https://github.com/seoynbnexus/flowx/blob/main/shared/services/meta-auth.service.js"
click node_meta_graph "https://github.com/seoynbnexus/flowx/blob/main/shared/services/meta-graph.service.js"
click node_ai "https://github.com/seoynbnexus/flowx/blob/main/src/modules/ai/ai.service.js"
click node_ai_provider "https://github.com/seoynbnexus/flowx/blob/main/shared/ai/provider.js"
click node_moderation "https://github.com/seoynbnexus/flowx/blob/main/shared/ai/moderation.service.js"
click node_media "https://github.com/seoynbnexus/flowx/blob/main/src/modules/media-library/media.service.js"
click node_posts "https://github.com/seoynbnexus/flowx/blob/main/src/modules/posts/post.service.js"
click node_campaign "https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/campaign.service.js"
click node_execution "https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/campaign-execution.service.js"
click node_webhooks "https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/meta-webhook.service.js"
click node_jobs "https://github.com/seoynbnexus/flowx/blob/main/src/jobs/worker.js"
click node_payments "https://github.com/seoynbnexus/flowx/blob/main/src/modules/payments/payment.service.js"
click node_razorpay "https://github.com/seoynbnexus/flowx/blob/main/src/modules/payments/razorpay.client.js"
click node_subscriptions "https://github.com/seoynbnexus/flowx/blob/main/src/modules/subscriptions/subscription.service.js"
click node_ledger "https://github.com/seoynbnexus/flowx/blob/main/shared/services/usage-ledger.service.js"
click node_analytics "https://github.com/seoynbnexus/flowx/blob/main/src/modules/analytics/admin.controller.js"
click node_database "https://github.com/seoynbnexus/flowx/blob/main/shared/database/connection.js"

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_auth,node_users,node_permissions,node_user toneBlue
class node_ai,node_moderation,node_media,node_posts toneAmber
class node_oauth,node_campaign,node_execution,node_webhooks toneMint
class node_payments,node_subscriptions,node_ledger toneRose
class node_app,node_routes,node_meta_auth,node_meta_graph,node_ai_provider,node_jobs,node_razorpay,node_analytics,node_database toneIndigo
```

## Components

### Accounts & access

- [Authentication](https://github.com/seoynbnexus/flowx/blob/main/src/modules/auth/auth.service.js): `src/modules/auth/auth.service.js`
- [User accounts](https://github.com/seoynbnexus/flowx/blob/main/src/modules/users/user.service.js): `src/modules/users/user.service.js`
- [Roles & permissions](https://github.com/seoynbnexus/flowx/blob/main/src/modules/permissions/permission.service.js): `src/modules/permissions/permission.service.js`

### Content & AI

- [AI generation](https://github.com/seoynbnexus/flowx/blob/main/src/modules/ai/ai.service.js): `src/modules/ai/ai.service.js`
- [AI moderation](https://github.com/seoynbnexus/flowx/blob/main/shared/ai/moderation.service.js): `shared/ai/moderation.service.js`
- [Media library](https://github.com/seoynbnexus/flowx/blob/main/src/modules/media-library/media.service.js): `src/modules/media-library/media.service.js`
- [Posts & promotions](https://github.com/seoynbnexus/flowx/blob/main/src/modules/posts/post.service.js): `src/modules/posts/post.service.js`

### Campaign operations

- [Social account linking](https://github.com/seoynbnexus/flowx/blob/main/src/modules/publisher-platforms/oauth.service.js): `src/modules/publisher-platforms/oauth.service.js`
- [Campaign management](https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/campaign.service.js): `src/modules/campaigns/campaign.service.js`
- [Campaign execution](https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/campaign-execution.service.js): `src/modules/campaigns/campaign-execution.service.js`
- [Meta webhooks](https://github.com/seoynbnexus/flowx/blob/main/src/modules/campaigns/meta-webhook.service.js): `src/modules/campaigns/meta-webhook.service.js`

### Payments & usage

- [Payments](https://github.com/seoynbnexus/flowx/blob/main/src/modules/payments/payment.service.js): `src/modules/payments/payment.service.js`
- [Subscriptions & plans](https://github.com/seoynbnexus/flowx/blob/main/src/modules/subscriptions/subscription.service.js): `src/modules/subscriptions/subscription.service.js`
- [Usage ledger](https://github.com/seoynbnexus/flowx/blob/main/shared/services/usage-ledger.service.js): `shared/services/usage-ledger.service.js`

### Runtime & integrations

- [Express application](https://github.com/seoynbnexus/flowx/blob/main/app.js): `app.js`
- [API routes](https://github.com/seoynbnexus/flowx/blob/main/src/routes/index.js): `src/routes/index.js`
- [Meta OAuth](https://github.com/seoynbnexus/flowx/blob/main/shared/services/meta-auth.service.js): `shared/services/meta-auth.service.js`
- [Meta Graph API](https://github.com/seoynbnexus/flowx/blob/main/shared/services/meta-graph.service.js): `shared/services/meta-graph.service.js`
- [AI providers](https://github.com/seoynbnexus/flowx/blob/main/shared/ai/provider.js): `shared/ai/provider.js`
- [Background jobs](https://github.com/seoynbnexus/flowx/blob/main/src/jobs/worker.js): `src/jobs/worker.js`
- [Razorpay](https://github.com/seoynbnexus/flowx/blob/main/src/modules/payments/razorpay.client.js): `src/modules/payments/razorpay.client.js`
- [Analytics dashboard](https://github.com/seoynbnexus/flowx/blob/main/src/modules/analytics/admin.controller.js): `src/modules/analytics/admin.controller.js`
- [MySQL database](https://github.com/seoynbnexus/flowx/blob/main/shared/database/connection.js): `shared/database/connection.js`

### Other components

- **Client or admin**

## Connections

- Client or admin → Express application: sends requests
- Express application → API routes: dispatches routes
- Authentication → MySQL database: reads and writes
- Authentication → User accounts: creates accounts
- Authentication → MySQL database: stores sessions
- Social account linking → Meta OAuth: builds auth URL
- Social account linking → Meta Graph API: fetches pages
- Social account linking → MySQL database: stores linked accounts
- AI generation → AI providers: requests generation
- AI generation → AI moderation: checks content
- AI generation → MySQL database: records usage
- Media library → MySQL database: stores media records
- Posts & promotions → MySQL database: persists posts
- Campaign management → MySQL database: persists campaigns
- Campaign execution → Meta Graph API: publishes campaign data
- Meta webhooks → MySQL database: records webhook events
- Background jobs → Campaign execution: runs scheduled work
- Payments → Razorpay: creates and verifies orders
- Payments → MySQL database: records payments
- Subscriptions & plans → MySQL database: reads and writes plans
- Usage ledger → MySQL database: records usage
- Analytics dashboard → MySQL database: queries metrics
