Feat/issues 346 347 348 349

[xeladev4]

PR: Close issues #346, #347, #348, #349

Summary

This PR delivers four assigned tasks in one branch:

• Add per-IP connection limits to SSE endpoint #346: Add per-IP and global connection limits to SSE endpoint
• Add stream creation templates to StreamCreationWizard #347: Add stream creation templates to StreamCreationWizard
• Write architecture and developer onboarding documentation #348: Write architecture and developer onboarding documentation
• Add per-IP connection limits to SSE endpoint #349: Add user stream summary endpoint with 30s caching

Changes

1) SSE connection protections and metrics (#346)

Backend:

• Added in-memory per-IP connection tracking in SSE service
• Enforced max 5 concurrent SSE connections per IP
• Enforced global max capacity from MAX_SSE_CONNECTIONS (default 10000)
• Returns 429 with Retry-After: 60 when per-IP limit is exceeded
• Returns 503 when global capacity is reached
• Cleans up IP map entries when all connections for an IP are closed
• Exposed per-IP peak connection metric in admin metrics

Files:

• backend/src/services/sse.service.ts
• backend/src/controllers/sse.controller.ts
• backend/src/routes/v1/events.routes.ts
• backend/src/routes/adminRoutes.ts
• backend/tests/sse.service.test.ts

2) User summary endpoint with cache (#349)

Backend:

• Added GET /v1/users/{address}/summary
• Returns:
  • totalStreamsCreated
  • totalStreamedOut (sum of outgoing withdrawn)
  • totalStreamedIn (sum of incoming withdrawn)
  • currentClaimable (sum of claimable across active incoming streams)
  • activeOutgoingCount
  • activeIncomingCount
• Added in-memory 30s cache for hot path
• Handles users with no streams (all zeros)
• Added tests for zero-state, aggregate correctness, and caching behavior

Files:

• backend/src/controllers/stream.controller.ts
• backend/src/routes/v1/user.routes.ts
• backend/tests/stream.test.ts

3) Stream creation wizard templates (#347)

Frontend:

• Added a template selection step at the start of wizard
• Built-in templates:
  • Monthly Salary
  • Weekly Subscription
  • One-time Grant
  • Custom
• Template selection pre-fills amount, duration, token, and description tag
• All pre-filled values remain editable in subsequent steps
• Added custom template save/load via localStorage

Files:

• frontend/components/stream-creation/StreamCreationWizard.tsx
• frontend/components/stream-creation/TemplateStep.tsx

4) Architecture + onboarding docs (#348)

Docs:

• Rewrote docs/ARCHITECTURE.md with:
  • Mermaid pipeline diagram (contract -> worker -> Prisma/Postgres -> SSE -> frontend)
  • Event data flow per event type, including paused/resumed model
  • Pause/resume timing model equations and explanation
  • Freighter challenge-sign -> JWT -> SSE subscribe auth flow
  • Redis pub/sub multi-instance behavior
• Added docs/DEVELOPMENT.md with:
  • Prerequisites (Rust, Node 20, Stellar CLI, Postgres, Redis optional)
  • Step-by-step local setup from clone to running full stack
  • Common issue troubleshooting (indexer sync, SSE drops, auth errors)
• Linked both docs from README.md

Files:

• docs/ARCHITECTURE.md
• docs/DEVELOPMENT.md
• README.md

Additional fix included

• Resolved duplicate import collision in backend/src/routes/v1/index.ts and mounted both admin route groups safely.

Verification

Attempted local checks:

• backend npm test
• frontend npm run lint

Could not complete in this environment because dependencies could not be installed under Node v23.8.0 and Prisma requires Node 20.19+, 22.12+, or 24+.

Commits

1. feat(backend): add SSE limits and user summary stats
2. feat(frontend): add stream creation template step
3. docs: add architecture and onboarding guides

Issue closure

Closes #346
Closes #347
Closes #348
Closes #349