docs/social_branding/CHANGELOGS.md

Changelogs (main ➜ feature-update)

Date: 26 Mar 2026
Scope: Diff between origin/main and feature-update

Summary

feature-update is a large feature + architecture update.

• Scale of change: 85 files changed, +11,633 / -3,266 lines.
• Primary outcomes:
  • Adds QScore integration and user-level caching.
  • Adds a Brand Score engine (with audit output, quick wins, and optional eventing).
  • Introduces a more explicit architecture: Adapters → Use-cases → Repositories → Engine.
  • Improves worker/job processing with job dispatching + idempotency.
  • Adds demo/dev ergonomics: no-auth mode, demo token, and /demo UI.
  • Adds significant test coverage and documentation.

---

What’s new (features added)

1) QScore integration

Goal: Fetch/compute QScore and persist a read-optimized snapshot for downstream UX and scoring.

Key additions:

• API module: app/api/v1/qscore.py
• Client: app/clients/qscore_client.py
• Service: app/services/qscore_service.py
• Schema types: app/schemas/qscore.py
• DB cache column via migration:
  • alembic/versions/20260325_000001_add_qscore_summary_to_social_users.py
• Model update:
  • app/models/user.py adds qscore_summary (JSONB)

Net effect: The service can expose QScore data and keep the latest snapshot in the user row for fast reads.

---

2) Brand Score engine (+ summaries)

Goal: Compute and explain a “Brand Score” with actionable guidance.

Key additions:

• Engine modules:
  • app/engine/brand_score_engine.py
  • app/engine/audit_engine.py
  • app/engine/persona_engine.py
  • app/engine/draft_engine.py
  • app/engine/calendar_engine.py
  • app/engine/contracts.py
  • app/engine/scoring_rules.py
• Eventing:
  • app/services/brand_score_eventing.py
• DB cache column via migration:
  • alembic/versions/20260325_000002_add_brand_score_summary_to_social_users.py
• Model update:
  • app/models/user.py adds brand_score_summary (JSONB)

Behavioral highlights:

• Brand score output includes structured “strengths” and top “quick wins” derived from audit explanations.

---

3) Job dispatcher + worker pipeline improvements

Goal: Make background job handling explicit, testable, and safer on retries.

Key additions:

• Job framework:
  • app/jobs/dispatcher.py (routes job_type → handler)
  • app/jobs/definitions.py
  • app/jobs/__init__.py

Notable behaviors:

• Optional idempotency key support (Redis SETEX, 24h TTL) to avoid double-processing when messages are re-delivered.

---

4) Demo/dev UX improvements

Goal: Run and validate the service without external auth dependencies in dev/demo scenarios.

Key additions:

• app/auth/dependencies.py
  • no_auth_mode (always treat caller as demo_user_id)
  • demo_auth_enabled + token value demo shortcut
• app/main.py
  • GET /demo serves app/static/demo.html (fallback redirects to /docs)
• app/static/demo.html (mini UI)

---

What changed (behavioral refactors)

APIs: “fat routes” ➜ use-case driven routes

Many endpoints were refactored to:

• Stop doing SQLAlchemy querying/ownership checks directly inside routers.
• Delegate to use-cases via provide_use_case(...).

Examples of refactored routers:

• app/api/v1/profiles.py
• app/api/v1/content.py
• app/api/v1/internal.py
• Dashboard state endpoint in app/main.py now delegates to app/use_cases/get_dashboard.py

Net effect: Controllers become thinner and easier to reason about; business and persistence logic becomes reusable and testable.

---

Scoring logic: service module ➜ pure engine module

• Previous: app/services/scoring_service.py contained large amounts of pure scoring logic.
• Now: app/services/scoring_service.py is a compatibility wrapper that re-exports scoring functions/constants from app/engine/scoring_rules.py.

Why: Centralizes domain logic in the Engine layer and keeps import stability for older code.

---

What was removed (or relocated)

1) app/services/branding_intelligence.py removed

• Deleted: app/services/branding_intelligence.py
• Replaced by layered structure:
  • Added: app/adapters/branding_intelligence.py

This is part of a broader “services → adapters” refactor.

2) Service modules moved under adapters

Renames (logical move; functionality preserved):

• app/services/ai_service.py → app/adapters/ai_service.py
• app/services/brightdata_service.py → app/adapters/brightdata_service.py
• app/services/scrapetable_service.py → app/adapters/scrapetable_service.py

---

Architecture: before vs after

Previous architecture (main)

Common traits observed in the diff:

• Routers frequently performed:
  • DB access (select, update, joins)
  • Ownership/security checks
  • Data merging/enrichment logic
  • Commit/flush patterns
• Most domain logic lived in service modules, often mixing:
  • domain rules
  • provider orchestration
  • persistence decisions

Typical pain points:

• Harder to test logic without DB + IO.
• Harder to reuse workflows between:
  • HTTP routes
  • background jobs
  • agent/worker flows
• High coupling between external providers and business logic.

---

Current architecture (feature-update)

The code is reorganized around clearer boundaries:

1. Adapters (app/adapters/)

   • External IO: AI providers, BrightData, Scrapetable, branding intelligence provider glue.

2. Use-cases (app/use_cases/)

   • Application workflows (orchestration):
     • validate inputs
     • call repos, engines, adapters
     • decide persistence / commit points

3. Repositories (app/repositories/)

   • Database access patterns:
     • fetch by clerk id
     • fetch profile for user
     • save scores/drafts

4. Engine (app/engine/)

   • Pure or mostly-pure domain logic:
     • scoring rules
     • auditing
     • persona generation
     • calendar/draft logic

5. API controllers (app/api/...)

   • Translate HTTP requests to use-case calls.
   • Convert errors to HTTP codes.

---

Why the new architecture is better

1) Testability

• Engine logic can be unit-tested without network or DB.
• Use-cases can be tested with mocked adapters and in-memory db sessions.

2) Separation of concerns (less coupling)

• External providers are isolated in adapters.
• Domain logic is isolated in engine modules.
• DB access is consolidated and reusable in repositories.

3) Reuse across execution contexts

The same use-cases can be invoked from:

• REST APIs
• workers/jobs
• agent flows

This reduces duplication and “slightly-different” implementations.

4) Safer background jobs

• Dispatcher introduces structured routing and idempotency support.
• Makes retries less risky and easier to reason about.

5) Better dev ergonomics

• No-auth mode and a demo UI make local validation faster.
• Less dependency on Clerk for basic smoke tests.

---

Developer-facing changes to be aware of

Authentication behavior

• app/auth/dependencies.py now supports:
  • global no-auth mode (treat all calls as demo_user_id)
  • demo token shortcut (token == demo)

DB migrations now required

• Brand/QScore summaries require running Alembic migrations before using those features.

Import path changes

• External integrations moved under app/adapters/*.
• Scoring logic moved to app/engine/scoring_rules.py (service remains as a compatibility re-export).

---

Tests added/updated

New tests:

• tests/test_engine.py
• tests/test_hardening.py
• tests/test_qscore_integration.py
• tests/test_rqx_formula.py
• tests/test_worker_convergence.py

Updated tests:

• tests/test_branding_intelligence.py

---

Documentation added

A significant set of planning/architecture docs was added, including:

• docs/PRD.md
• docs/qscore-integration.md
• docs/eventing-contract.md
• plus multiple architecture/plan/audit checklists under docs/

---

Quick file index (most important additions)

• Engine: app/engine/*
• Use-cases: app/use_cases/*
• Repositories: app/repositories/*
• QScore: app/api/v1/qscore.py, app/services/qscore_service.py, app/clients/qscore_client.py, app/schemas/qscore.py
• DB migrations: alembic/versions/20260325_000001_*, alembic/versions/20260325_000002_*
• Demo: app/static/demo.html, GET /demo in app/main.py
• Jobs: app/jobs/dispatcher.py