backend-and-architecture

[bakarezainab]

Description

docs/ARCHITECTURE.md Documents IndexerState.lastLedger (not lastIndexedLedger)
Describes StreamEvent persistence as per-event findUnique + upsert on (transactionHash, eventType), not createMany with skipDuplicates
Adds a model/field reference table for User, Stream, StreamEvent, and IndexerState
backend/prisma/schema.prisma

Adds IndexerState with lastLedger
Adds @@unique([transactionHash, eventType]) on StreamEvent to match the upsert key
Removes url from the datasource block (Prisma 7 expects it in prisma.config.ts, which this repo already has)

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test addition or update

Related Issues

Closes #838
Closes #840
Closes #841
Closes #842

Changes Made

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

Test Steps

cd backend && npx vitest run tests/sse.service.test.ts
# ✓ 3 passed

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published
• I have checked for breaking changes and documented them if applicable

Additional Notes

[Backend] SSE backpressure on slow clients
backend/src/services/sse.service.ts

writeToClient() checks res.write() return value; on false, pauses the client until drain
Drops clients when writableLength exceeds 64 KB while paused
Removes clients on write failure in broadcast() (same as sendHeartbeat())
Adds getSlowClientsDropped() for observability
Adds periodic sendHeartbeat() (30s interval when clients are connected)
backend/tests/sse.service.test.ts — 3 tests, all passing:

Write throws → failing client removed, healthy client still receives events
Write returns false + buffer over threshold → slow client dropped, others unaffected
Same slow-client handling in sendHeartbeat()
Also added vitest, supertest, and @types/supertest to backend/package.json (existing tests already imported them but they were not declared).

[ogazboiz]

heads up: main's ci was broken (the Backend CI and Backend Docker Image CI jobs) until the fixes in #969 and #974 just landed, so the red backend/docker checks on this pr are almost certainly stale, they ran against the broken main. please rebase to re-test against the now-green main: git fetch origin && git rebase origin/main && git push --force-with-lease. once it's green i'll review and merge. (if a non-backend check like Frontend CI is still red after the rebase, that part is a real issue worth a look, since frontend ci was passing on main.)