feat(scripts): reproducible demo seed via snapshot dump/load

[mehmetborasarioglu]

Summary

Adds a self-contained pipeline that captures the current hand-crafted
demo state (78 users, 288 posts, 6 active + 48 past mentorships,
45 ratings, 100 messages, 389 binary uploads) into a portable
snapshot and replays it on a fresh DB without any HTTP/API calls.

After this lands, a teammate can reach the full demo state with two
commands on a fresh checkout:

docker compose up -d
./scripts/seed.sh load

Load time on a working stack: ~1.5 seconds. No OpenAI / Unsplash /
Resend / thispersondoesnotexist dependencies at load time — every binary
the demo shows is committed under scripts/seed_snapshot_data/uploads/.

What's new

• scripts/seed.sh — single bash entry point. Subcommands:
  setup, dump [DIR], load [DIR], status. Bootstraps a local
  .venv on first run, pre-flights Docker, and dispatches to the
  Python tooling.
• scripts/seed_snapshot.py — psycopg COPY + docker cp based
  dump/load. Writes seed-owned rows in FK order, restores the
  backend uploads tree. Idempotent: DELETE-then-COPY on load, so
  a re-load over an existing state cleanly converges.
• scripts/seed_snapshot_data/ — committed snapshot artifact
  (~109 MB). 27 CSVs in data/, 151 photos + 238 attachments in
  uploads/, and a manifest.json with row counts + id-sequence
  high-water marks.
• scripts/seed_demo_*.py — the full Phase A-V builder that
  produced the snapshot. Phase A now auto-applies city → lat/lon
  coordinates and backfills mentors.bio, mentors.mentoring_goals,
  mentees.background_info, mentees.goals from the markdown
  corpus, plus tops up any mentor with 0 availability slots. That
  makes the snapshot regenerable end-to-end without manual fixups.
• docker-compose.yml — three new env defaults required by the
  seed flow: APP_RATELIMIT_ENABLED, FOLLOW_GRAPH_SYNC_ENABLED,
  FOLLOW_RANKER. All default to safe production values; the seed
  scripts flip them per env when needed.
• .gitignore — .venv/, .env.* (with example overrides),
  seed-pipeline runtime artifacts under scripts/.seed_*.json and
  scripts/.seed_*_tmp/.

What's in the demo state

Entity	Count
Users	78 (1 admin + 20 mentors + 57 mentees)
Profile photos	78 (1 per user)
Feed posts	288, 71 with attached images
Comments / likes	655 / 852
Comment likes	1 639
Follow edges	377
Mentorships (active)	6
Mentorships (past)	48
Mentor ratings	45 (mean ~3.9 / 5)
Messages	100
Tasks	34 (7 with attached PDF files)
Milestones	28
Meetings	51 (mix of completed + scheduled)
Mentor-pair conversations	3

Files in the snapshot directory

scripts/seed_snapshot_data/
├── data/                  # 27 CSVs, FK-ordered
├── uploads/
│   ├── photos/            # 151 profile photos
│   └── attachments/       # 238 post images + task PDFs
└── manifest.json

How load works

1. Pre-flight checks: docker daemon up, db + backend containers running.
2. DELETE FROM <table> WHERE <seed-filter> for every dumped table,
   child-first, leaves bootstrap users (admin@group7.com) untouched.
3. COPY <table> (...) FROM STDIN WITH (FORMAT csv, HEADER false)
   for every CSV, parent-first.
4. setval(pg_get_serial_sequence(...), MAX(id)) on every relevant
   sequence so subsequent UI registrations don't collide.
5. docker cp scripts/seed_snapshot_data/uploads/{photos,attachments} <backend>:/app/uploads/ to restore the binary files. Existing
   files in the container are left in place (orphans are harmless;
   nothing in the DB references them).

Test plan

• On a checkout of this branch, docker compose up -d brings
  the stack up cleanly.
• ./scripts/seed.sh setup creates .venv/ and installs
  scripts/requirements-seed.txt.
• ./scripts/seed.sh status shows seed counts (0 if first run).
• ./scripts/seed.sh load finishes in under 5 seconds and
  reports the row totals listed in the table above.
• Login as defne.korkmaz.74@seed.test / Seed1234! on the
  web and on the mobile app — both should show the demo persona,
  her past mentorships, AI match recommendations, and her profile
  photo.
• Login as yildiz.demir.78@seed.test / Seed1234! and confirm
  the active mentorship with Rıza Yavuz shows tasks (with PDF
  attachments), milestones, meeting notes, and a message thread.
• ./scripts/seed.sh dump re-captures current state to the
  same snapshot directory in under 15 seconds, leaving the manifest
  with up-to-date counts.

Notes for reviewers

• The snapshot directory is ~109 MB and is committed directly
  (no git LFS). The trade-off is that a fresh checkout has the full
  demo immediately, with no external service round-trips. Open to
  switching to LFS if size becomes a problem.
• The Phase A-V builder (scripts/seed_demo_*.py) is what produced
  the snapshot. It's kept around so future demo iterations can
  regenerate the snapshot from updated markdown content — but the
  builder is not required for ./scripts/seed.sh load, which
  only needs the snapshot directory.
• APP_RATELIMIT_ENABLED=true is the safe production default, so
  the docker-compose change does not loosen any prod-relevant
  setting. Local dev can flip it via .env when needed.