# rjmad1/fluxora architecture

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

- Interactive diagram: https://gitdiagram.com/rjmad1/fluxora
- Repository: https://github.com/rjmad1/fluxora

## Overview

1. **Repository shape**
   - This is a **monorepo for the Fluxora platform**, not just an app codebase.
   - It combines **product/architecture governance**, **spec-driven planning artifacts**, and two runtime applications: a **NestJS backend** and a **Next.js frontend**.

2. **Governance and spec pipeline**
   - The `.specify`, `.cursor`, and `.agents` folders hold **Spec-Kit workflows, prompts, templates, and agent integrations**.
   - `specs/001-*` and `specs/002-*` contain feature-level architecture/spec/plan/task artifacts.
   - `PM_Deliverables/` and `Functional Requirements/` are upstream business inputs, so architecture is intentionally **documentation-driven before implementation**.

3. **Frontend boundary**
   - `apps/frontend` is a **Next.js App Router** client.
   - It has separate surfaces for:
     - a **workspace/admin experience** at `src/app/workspaces`
     - a **tokenized approval portal** at `src/app/approval/[token]`
   - Shared UI components include `Composer` and `AnalyticsDashboard`, indicating the frontend is both an **operations console** and an **approval workflow entry point**.

4. **Backend boundary**
   - `apps/backend` is a **NestJS modular API**.
   - The code is split into feature domains rather than a single monolith:
     - `ai`
     - `analytics`
     - `asset`
     - `identity`
     - `observability`
     - `publishing`
     - `secrets`
     - `tenant`
   - This suggests a **domain-oriented backend** where each module owns its own controllers/services and can be diagrammed as separate backend subsystems.

5. **Tenant isolation and identity**
   - The `tenant` module and `tenant.interceptor.ts` indicate **tenant context injection/enforcement** at request time.
   - `prisma.service.ts`, `schema.prisma`, and the `prisma/migrations/rls_init.sql` file show that **PostgreSQL row-level security** is part of the isolation strategy.
   - `identity/keycloak.module.ts` makes **Keycloak the identity boundary**, likely handling OIDC/OAuth2 authentication and tenant/user access control.

6. **Publishing and approval workflow**
   - The `publishing` module is the most workflow-heavy part of the backend.
   - Files like `publish.controller.ts`, `approval.controller.ts`, `publish.processor.ts`, `publish.activities.ts`, and `token-refresh.activities.ts` show a split between:
     - API entry points
     - asynchronous processing
     - workflow activities
     - token refresh/adaptor logic
   - This is the likely core of the product’s **scheduling, approval, and distribution pipeline**.

7. **External channel adapters**
   - `publishing/adapters.service.ts` implies the backend wraps external social platforms behind an internal adapter layer.
   - In architecture terms, Fluxora’s custom logic sits behind a **provider abstraction**, so channel integrations can be swapped or extended without changing the rest of the platform.

8. **Asset and content handling**
   - The `asset` module is a separate boundary for **media/content management**.
   - Because the README frames Fluxora around content adaptation and distribution, the asset subsystem is likely the hub for **upload, persistence, and preparation of media artifacts** before publishing.

9. **AI and compliance**
   - `ai/brand-compliance.service.ts` shows a dedicated AI-facing service for **brand-voice or policy validation**.
   - This aligns with the repository’s stated differentiator around **AI content operations** rather than generic LLM usage.
   - The AI layer is therefore a **guardrail/service module**, not the primary app surface.

10. **Secrets, observability, and event boundaries**
   - `secrets/vault.service.ts` and `oauth.controller.ts` isolate sensitive material such as **OAuth tokens, API keys, or certificates** behind a Vault-backed service boundary.
   - `observability/otel.middleware.ts` and `outbox.interceptor.ts` indicate instrumentation plus an **outbox-style event capture path** for reliable telemetry or domain events.
   - This suggests the runtime is designed to emit **traces/events/metrics** without coupling them directly to business handlers.

11. **Infrastructure and platform integration**
   - `infra/kong/kong.yml` shows an **API gateway layer** in front of the backend.
   - `docker-compose.infra.yaml` implies a local/integration deployment environment for platform services.
   - The README’s target stack also names **Temporal, Kafka, PostgreSQL, ClickHouse, OpenSearch, MinIO, CloudFront, Vault, and OpenTelemetry**, so the intended architecture is a **service-oriented platform with workflow, eventing, storage, and analytics backends**.

12. **Diagramming takeaway**
   - A good architecture diagram for this repo should separate:
     - **governance/spec artifacts**
     - **frontend workspaces + approval portal**
     - **NestJS backend domains**
     - **identity/tenant enforcement**
     - **publishing workflow and adapter layer**
     - **secrets/observability infrastructure**
     - **external platform services**
   - The key architectural theme is **strict multi-tenant isolation with workflow-driven publishing and extensible integrations**, backed by spec-first governance.

Main entry points: [`apps/backend/src/app.module.ts`](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/app.module.ts) (API Shell), [`apps/backend/src/publishing/publishing.module.ts`](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/publishing/publishing.module.ts) (Publishing), [`.specify`](https://github.com/rjmad1/fluxora/blob/main/.specify) (Spec Kit), [`apps/frontend/src/app/workspaces/page.tsx`](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/workspaces/page.tsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_speckit["Spec Kit<br/>workflow/spec tooling<br/>[.specify]"]
  node_cursor_agents["Agent Skills<br/>agent prompts<br/>[.cursor]"]
  node_pm_deliverables["PM Inputs<br/>product docs"]
  node_requirements["Requirements<br/>business specs"]
  node_platform_specs["Feature Specs<br/>feature plans"]
  node_portal_specs["Portal Specs<br/>feature plans"]
end

subgraph group_frontend["Frontend"]
  node_workspace_ui["Workspace UI<br/>next app<br/>[page.tsx]"]
  node_approval_portal["Approval Portal<br/>next app<br/>[page.tsx]"]
  node_composer["Composer<br/>ui component<br/>[Composer.tsx]"]
  node_analytics_dashboard["Analytics<br/>ui component"]
  node_app_shell["App Shell<br/>next shell<br/>[layout.tsx]"]
end

subgraph group_backend["Backend"]
  node_nest_app["API Shell<br/>nest bootstrap<br/>[app.module.ts]"]
  node_tenant["Tenant<br/>isolation module<br/>[tenant.module.ts]"]
  node_identity["Identity<br/>auth module<br/>[keycloak.module.ts]"]
  node_publishing["Publishing<br/>workflow module"]
  node_asset["Assets<br/>content module<br/>[asset.module.ts]"]
  node_ai["AI Guardrails<br/>ai module<br/>[ai.module.ts]"]
  node_secrets["Secrets<br/>vault module<br/>[secrets.module.ts]"]
  node_observability["Observability<br/>telemetry layer<br/>[otel.middleware.ts]"]
end

subgraph group_platform["Platform"]
  node_gateway["Gateway<br/>[kong.yml]"]
  node_infra_stack["Infra Stack<br/>dev infra"]
  node_data_plane[("Data Plane<br/>runtime services")]
end

node_pm_deliverables -->|"shape inputs"| node_speckit
node_requirements -->|"define scope"| node_speckit
node_speckit -->|"produces"| node_platform_specs
node_speckit -->|"produces"| node_portal_specs
node_cursor_agents -.->|"assist"| node_speckit
node_platform_specs -.->|"guides"| node_workspace_ui
node_portal_specs -.->|"guides"| node_approval_portal
node_app_shell -->|"hosts"| node_workspace_ui
node_app_shell -->|"hosts"| node_approval_portal
node_composer -->|"supports"| node_workspace_ui
node_analytics_dashboard -->|"supports"| node_workspace_ui
node_gateway -->|"routes"| node_nest_app
node_nest_app -->|"loads"| node_tenant
node_nest_app -->|"loads"| node_identity
node_nest_app -->|"loads"| node_publishing
node_nest_app -->|"loads"| node_asset
node_nest_app -->|"loads"| node_ai
node_nest_app -->|"loads"| node_secrets
node_nest_app -->|"loads"| node_observability
node_tenant -->|"enforces"| node_data_plane
node_identity -->|"authenticates"| node_data_plane
node_publishing -->|"uses"| node_asset
node_publishing -->|"checks"| node_ai
node_publishing -->|"reads"| node_secrets
node_publishing -->|"emits"| node_observability
node_asset -->|"stores"| node_data_plane
node_ai -->|"queries"| node_data_plane
node_secrets -->|"backs"| node_data_plane
node_observability -->|"ships"| node_data_plane
node_infra_stack -.->|"provisions"| node_data_plane

click node_speckit "https://github.com/rjmad1/fluxora/blob/main/.specify"
click node_cursor_agents "https://github.com/rjmad1/fluxora/blob/main/.cursor"
click node_pm_deliverables "https://github.com/rjmad1/fluxora/tree/main/PM_Deliverables"
click node_requirements "https://github.com/rjmad1/fluxora/tree/main/Functional Requirements"
click node_platform_specs "https://github.com/rjmad1/fluxora/tree/main/specs/001-platform-architecture"
click node_portal_specs "https://github.com/rjmad1/fluxora/tree/main/specs/002-social-adapters-and-portal"
click node_workspace_ui "https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/workspaces/page.tsx"
click node_approval_portal "https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/approval/[token]/page.tsx"
click node_composer "https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/components/Composer.tsx"
click node_analytics_dashboard "https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/components/AnalyticsDashboard.tsx"
click node_app_shell "https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/layout.tsx"
click node_nest_app "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/app.module.ts"
click node_tenant "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/tenant/tenant.module.ts"
click node_identity "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/identity/keycloak.module.ts"
click node_publishing "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/publishing/publishing.module.ts"
click node_asset "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/asset/asset.module.ts"
click node_ai "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/ai/ai.module.ts"
click node_secrets "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/secrets/secrets.module.ts"
click node_observability "https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/observability/otel.middleware.ts"
click node_gateway "https://github.com/rjmad1/fluxora/blob/main/infra/kong/kong.yml"
click node_infra_stack "https://github.com/rjmad1/fluxora/blob/main/docker-compose.infra.yaml"

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_speckit,node_cursor_agents,node_pm_deliverables,node_requirements,node_platform_specs,node_portal_specs toneBlue
class node_workspace_ui,node_approval_portal,node_composer,node_analytics_dashboard,node_app_shell toneAmber
class node_nest_app,node_tenant,node_identity,node_publishing,node_asset,node_ai,node_secrets,node_observability toneMint
class node_gateway,node_infra_stack,node_data_plane toneRose
```

## Components

### Governance

Spec-first planning, prompts, and product artifacts.

- [Spec Kit](https://github.com/rjmad1/fluxora/blob/main/.specify): workflow/spec tooling · Spec-driven workflows, templates, and agent integrations. · `.specify`
- [Agent Skills](https://github.com/rjmad1/fluxora/blob/main/.cursor): agent prompts · Cursor and agent skill packs for spec analysis, planning, and implementation. · `.cursor`
- [PM Inputs](https://github.com/rjmad1/fluxora/tree/main/PM_Deliverables): product docs · Upstream strategy, PRD, personas, backlog, and metrics artifacts. · `PM_Deliverables`
- [Requirements](https://github.com/rjmad1/fluxora/tree/HEAD/Functional%20Requirements): business specs · Functional requirements and source business inputs. · `Functional Requirements`
- [Feature Specs](https://github.com/rjmad1/fluxora/tree/main/specs/001-platform-architecture): feature plans · Spec, plan, and task artifacts for platform and portal work. · `specs/001-platform-architecture`
- [Portal Specs](https://github.com/rjmad1/fluxora/tree/main/specs/002-social-adapters-and-portal): feature plans · Spec, plan, and task artifacts for adapters and portal work. · `specs/002-social-adapters-and-portal`

### Frontend

Next.js surfaces for workspace operations and approvals.

- [Workspace UI](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/workspaces/page.tsx): next app · Admin/workspace experience in the Next.js App Router. · `apps/frontend/src/app/workspaces/page.tsx`
- [Approval Portal](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/approval/[token]/page.tsx): next app · Token-based approval surface for review and consent flows. · `apps/frontend/src/app/approval/[token]/page.tsx`
- [Composer](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/components/Composer.tsx): ui component · Shared content composition and editing surface. · `apps/frontend/src/components/Composer.tsx`
- [Analytics](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/components/AnalyticsDashboard.tsx): ui component · Shared dashboard for performance and operational insight. · `apps/frontend/src/components/AnalyticsDashboard.tsx`
- [App Shell](https://github.com/rjmad1/fluxora/blob/main/apps/frontend/src/app/layout.tsx): next shell · Root layout and page composition for the frontend. · `apps/frontend/src/app/layout.tsx`

### Backend

NestJS domain services, workflow, isolation, and integrations.

- [API Shell](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/app.module.ts): nest bootstrap · Backend application bootstrap and module assembly. · `apps/backend/src/app.module.ts`
- [Tenant](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/tenant/tenant.module.ts): isolation module · Tenant context injection and request-time enforcement. · `apps/backend/src/tenant/tenant.module.ts`
- [Identity](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/identity/keycloak.module.ts): auth module · Keycloak-backed authentication and access boundary. · `apps/backend/src/identity/keycloak.module.ts`
- [Publishing](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/publishing/publishing.module.ts): workflow module · Publish, approval, processor, activities, and adapter orchestration. · `apps/backend/src/publishing/publishing.module.ts`
- [Assets](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/asset/asset.module.ts): content module · Media and content management boundary. · `apps/backend/src/asset/asset.module.ts`
- [AI Guardrails](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/ai/ai.module.ts): ai module · Brand and policy compliance checks for content operations. · `apps/backend/src/ai/ai.module.ts`
- [Secrets](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/secrets/secrets.module.ts): vault module · Secure handling of OAuth tokens, keys, and certificates. · `apps/backend/src/secrets/secrets.module.ts`
- [Observability](https://github.com/rjmad1/fluxora/blob/main/apps/backend/src/observability/otel.middleware.ts): telemetry layer · OpenTelemetry middleware and outbox capture for runtime signals. · `apps/backend/src/observability/otel.middleware.ts`

### Platform

Infrastructure, gateway, and external runtime dependencies.

- [Gateway](https://github.com/rjmad1/fluxora/blob/main/infra/kong/kong.yml): api gateway · Kong gateway configuration in front of backend services. · `infra/kong/kong.yml`
- [Infra Stack](https://github.com/rjmad1/fluxora/blob/main/docker-compose.infra.yaml): dev infra · Local integration environment for platform services. · `docker-compose.infra.yaml`
- **Data Plane**: runtime services · PostgreSQL, Temporal, Kafka, ClickHouse, OpenSearch, MinIO, Vault, and telemetry backends.

## Connections

- PM Inputs → Spec Kit: shape inputs · Business artifacts feed the spec-first workflow.
- Requirements → Spec Kit: define scope · Functional requirements inform feature specs and plans.
- Spec Kit → Feature Specs: produces · Spec Kit creates architecture and implementation artifacts.
- Spec Kit → Portal Specs: produces · Spec Kit creates feature-level artifacts for portal work.
- Agent Skills → Spec Kit: assist · Agent skills support the spec pipeline and implementation flow.
- Feature Specs → Workspace UI: guides · Platform architecture informs the admin workspace UI.
- Portal Specs → Approval Portal: guides · Portal specs drive the approval experience.
- App Shell → Workspace UI: hosts · Root app shell composes the workspace route surface.
- App Shell → Approval Portal: hosts · Root app shell composes the approval route surface.
- Composer → Workspace UI: supports · Composer powers content creation and editing flows.
- Analytics → Workspace UI: supports · Dashboard provides operational insight in the workspace.
- Gateway → API Shell: routes · API gateway fronts the NestJS backend.
- API Shell → Tenant: loads · Application bootstrap includes tenant enforcement.
- API Shell → Identity: loads · Application bootstrap includes identity integration.
- API Shell → Publishing: loads · Application bootstrap includes the publish workflow domain.
- API Shell → Assets: loads · Application bootstrap includes content management.
- API Shell → AI Guardrails: loads · Application bootstrap includes AI compliance services.
- API Shell → Secrets: loads · Application bootstrap includes secret handling.
- API Shell → Observability: loads · Application bootstrap includes telemetry and outbox hooks.
- Tenant → Data Plane: enforces · Tenant module relies on PostgreSQL row-level security and tenant-aware persistence.
- Identity → Data Plane: authenticates · Identity boundary depends on platform identity and secure runtime services.
- Publishing → Assets: uses · Publishing orchestrates asset preparation before distribution.
- Publishing → AI Guardrails: checks · Publishing invokes brand compliance guardrails.
- Publishing → Secrets: reads · Publishing accesses provider credentials and tokens.
- Publishing → Observability: emits · Publishing produces workflow telemetry and domain events.
- Assets → Data Plane: stores · Assets persist in platform storage and data services.
- AI Guardrails → Data Plane: queries · AI services call into model- and data-backed runtime services.
- Secrets → Data Plane: backs · Vault-backed secrets are part of the platform data plane.
- Observability → Data Plane: ships · Telemetry and outbox data flow into the platform services.
- Infra Stack → Data Plane: provisions · Local infrastructure brings up the platform runtime dependencies.