rjmad1/fluxora

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.