feat: add search and analytics modules (closes #1012, #1013, #1014, #1015)

.gitignore

@@ -35,3 +35,7 @@ Thumbs.db
 
 issue.md
 pr.md
+
+...
+.npm_cache/
+

.husky/commit-msg

@@ -1,4 +1,3 @@
 #!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh" 2>/dev/null || true
 
 npx --no -- commitlint --edit "$1"

.husky/pre-commit

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh" 2>/dev/null || true
 
 # Block staged .env files (not .env.example)
 if git diff --cached --name-only | grep -E "(^|/)\.env$" > /dev/null 2>&1; then
@@ -22,4 +21,7 @@ if [ -n "$STAGED_RS" ]; then
 fi
 
 # Run lint-staged in frontend-scaffold
-cd frontend-scaffold && npx lint-staged
+(cd frontend-scaffold && npx lint-staged)
+
+# Run lint + format on staged backend files
+(cd backend && npx lint-staged)

backend/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

backend/.env.example

@@ -14,6 +14,9 @@ DATABASE_URL=postgresql://tipz:tipz@localhost:5432/tipz?schema=public
 
 # Redis (used by BullMQ queues + caching + rate limiting + socket adapter)
 REDIS_URL=redis://localhost:6379
+# Attaches the Socket.IO Redis adapter so realtime rooms are shared across horizontally scaled instances.
+# Set to false for a single-instance/local dev setup that doesn't need cross-instance fan-out.
+REALTIME_REDIS_ADAPTER_ENABLED=true
 
 # Auth (Stellar wallet challenge/JWT)
 JWT_SECRET=change-me-in-production
@@ -32,6 +35,37 @@ CONTRACT_ID=
 INDEXER_POLL_INTERVAL_MS=5000
 INDEXER_START_LEDGER=
 
+# Credit score recompute schedule (cron expression for BullMQ repeatable job)
+CREDIT_RECOMPUTE_CRON=0 */6 * * *
+
+# Credit score weights and configuration (optional — defaults provided)
+# Weights as percentages (must sum to <= 100)
+CREDIT_SCORE_WEIGHT_BASE=40
+CREDIT_SCORE_WEIGHT_TIP=20
+CREDIT_SCORE_WEIGHT_X=30
+CREDIT_SCORE_WEIGHT_AGE=10
+
+# Divisors for converting raw signals to scores
+CREDIT_SCORE_DIVISOR_TIP=10000000
+CREDIT_SCORE_DIVISOR_FOLLOWER=50
+CREDIT_SCORE_DIVISOR_ENGAGEMENT=10
+CREDIT_SCORE_DIVISOR_AGE=10
+
+# Caps for sub-scores
+CREDIT_SCORE_CAP_BASE=40
+CREDIT_SCORE_CAP_MAX=100
+CREDIT_SCORE_CAP_X_SUB=50
+CREDIT_SCORE_CAP_AGE_SUB=100
+CREDIT_SCORE_CAP_TIP_SUB=100
+
+# Cache TTL for credit scores in seconds
+CREDIT_SCORE_CACHE_TTL_SECONDS=300
+
+# Withdrawals
+WITHDRAWAL_MIN_AMOUNT_STROOPS=10000000
+# Withdrawal fee, in basis points (1/100th of a percent). 200 = 2%.
+WITHDRAWAL_FEE_BPS=200
+
 # X (Twitter) API — credit score signals
 X_API_BEARER_TOKEN=
 X_API_BASE_URL=https://api.twitter.com/2

backend/.prettierignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+coverage/
+build/
+*.js
+*.d.ts

backend/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "arrowParens": "always"
+}

backend/README.md

@@ -36,17 +36,17 @@ It covers the definition of done, module conventions, and local verification ste
 
 ## Tech stack
 
-| Concern        | Choice                                   |
-| -------------- | ---------------------------------------- |
-| Language       | TypeScript (Node.js ≥ 20, ESM)           |
-| HTTP framework | Express                                  |
-| ORM / DB       | Prisma + PostgreSQL                      |
-| Cache / queues | Redis + BullMQ                           |
-| Realtime       | Socket.IO                                |
-| Chain access   | `@stellar/stellar-sdk` (Soroban RPC)     |
-| Validation     | Zod                                      |
-| Logging        | Pino                                     |
-| Tests          | Vitest + Supertest                       |
+| Concern        | Choice                               |
+| -------------- | ------------------------------------ |
+| Language       | TypeScript (Node.js ≥ 20, ESM)       |
+| HTTP framework | Express                              |
+| ORM / DB       | Prisma + PostgreSQL                  |
+| Cache / queues | Redis + BullMQ                       |
+| Realtime       | Socket.IO                            |
+| Chain access   | `@stellar/stellar-sdk` (Soroban RPC) |
+| Validation     | Zod                                  |
+| Logging        | Pino                                 |
+| Tests          | Vitest + Supertest                   |
 
 ---
 
@@ -104,13 +104,27 @@ The dev server uses [`tsx watch`](https://github.com/privatenumber/tsx) — no n
 npm run dev          # starts tsx watch src/server.ts → http://localhost:4000/health
 ```
 
+**Git hooks**
+
+After `npm install`, Husky installs a `pre-commit` hook that runs `lint-staged` on
+staged `backend/**/*.ts` files. It will auto-fix lint issues (ESLint) and apply
+Prettier formatting where possible; if a file cannot be fixed automatically the
+commit is blocked so you can fix it manually.
+
+```bash
+cd backend
+npm install          # runs `husky` via the prepare script and installs the hook
+```
+
+To skip the hook in an emergency: `git commit --no-verify`.
+
 **Hot reload behaviour**
 
-| Change type | Behaviour |
-|---|---|
-| TypeScript source files | Automatic restart (tsx watch detects the change) |
-| `.env` file | **Not** auto-reloaded — restart the process manually after editing `.env` |
-| `prisma/schema.prisma` | Run `npm run prisma:generate` then restart |
+| Change type             | Behaviour                                                                 |
+| ----------------------- | ------------------------------------------------------------------------- |
+| TypeScript source files | Automatic restart (tsx watch detects the change)                          |
+| `.env` file             | **Not** auto-reloaded — restart the process manually after editing `.env` |
+| `prisma/schema.prisma`  | Run `npm run prisma:generate` then restart                                |
 
 **Port config** — set `PORT` in your `.env` (default `4000`). The value is
 validated at startup via `src/config/env.ts`; the server refuses to start if

backend/docker-compose.yml

@@ -1,5 +1,8 @@
-# Local infrastructure for backend development: PostgreSQL + Redis.
-# Usage:  docker compose -f backend/docker-compose.yml up -d
+# Local infrastructure for backend development: PostgreSQL, Redis, and the backend app.
+# Usage:  docker compose -f backend/docker-compose.yml up
+#
+# One-command startup — brings up Postgres, Redis, and the backend together.
+# The app container waits for both services to be healthy before starting.
 services:
   postgres:
     image: postgres:16-alpine
@@ -25,6 +28,32 @@ services:
       - '6379:6379'
     volumes:
       - tipz_redisdata:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      NODE_ENV: development
+      PORT: 3000
+      DATABASE_URL: postgresql://tipz:tipz@postgres:5432/tipz
+      REDIS_URL: redis://redis:6379
+    env_file:
+      - path: .env
+        required: false
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
 
 volumes:
   tipz_pgdata: