Vadym Samoilenko 8337bab5f7 Add README with setup, deploy, and project structure

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-17 12:03:04 +01:00

2.8 KiB

Raw Permalink Blame History

Barclays BMB Banner Visualiser

AI-powered banner creation tool for Barclays Mobile Banking campaign managers.

Brief → compliant copy variants → DAM image + icon → in-situ preview → PDF contact sheet + Workfront CSV

Live: https://optical-dev.oliver.solutions/barclays-banner-builder/

Stack

Layer	Tech
Frontend	React 18 + Vite + TypeScript + TailwindCSS + shadcn/ui
Backend	FastAPI (Python 3.12) + SQLAlchemy 2.0 async
Queue	RQ + Redis (HTTP polling — no WebSocket)
DB	PostgreSQL 16 + pgvector
AI	OpenAI `gpt-5.4-mini` + `text-embedding-3-small` (RAG)
PDF	WeasyPrint
Deploy	Docker Compose + Apache reverse proxy

Quick start (dev)

cp .env.example .env
# Set OPENAI_API_KEY in .env

docker compose up -d --build
docker compose exec api alembic upgrade head
docker compose exec api python scripts/seed_admin.py
docker compose exec api python scripts/ingest_rag.py
docker compose exec api python scripts/index_icons.py

Frontend: http://localhost:5174
API docs: http://localhost:8010/docs
Login: admin@barclays.com / change_me_password

Deploy (Ubuntu + Apache)

# Clone once:
git clone <repo> /opt/barclays-banner-builder

# Every deploy (idempotent):
bash /opt/barclays-banner-builder/deploy.sh

# Options:
bash deploy.sh --reindex        # force re-embed RAG + icons
bash deploy.sh --skip-frontend  # backend-only update

The script handles: Docker build (with cache), DB migrations, first-run seeding, npm build, Apache config patching.

Key rules

No WebSocket — all async work uses POST → 202 + job_id → GET /api/jobs/{id} polling
OpenAI only — model gpt-5.4-mini, key in .env only (never committed)
System prompt editable from /admin — full version history kept for FCA audit
Character limits enforced server-side — short_title ≤ 32, long_body ≤ 128, cta ≤ 50
DAM mock mode — if ADOBE_DAM_API_BASE_URL is empty, mock client is used automatically

Project structure

backend/app/
  api/         — FastAPI routers
  models/      — SQLAlchemy models
  services/    — copy_generation, exporter, adobe_dam_client
  llm/         — OpenAI client wrapper
  rag/         — pgvector cosine retrieval
  workers/     — RQ tasks (generate_copy, render_pdf)
  prompts/     — system_prompt.md (initial seed)

frontend/src/
  pages/       — BriefEditor, VariantsGrid, BannerEditor, ExportPage, AdminPage, LoginPage
  lib/         — jobPolling.ts
  store/       — Zustand auth store

rag-corpus/    — Consumer Duty, Consumer Understanding, Regulators .docx
assets/        — illustrations/ (PNG icons) + templates/
deploy/        — apache-barclays.conf (Apache Include fragment)
scripts/       — index_icons.py, ingest_rag.py, seed_admin.py

2.8 KiB Raw Permalink Blame History