Merge branch 'main' into docs/849-indexer-operational-runbook

Author: extolkom

CODE_OF_CONDUCT.md

@@ -1,16 +1,6 @@
 # Contributor Covenant Code of Conduct
 
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
 
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
 
 ## Our Standards
 
@@ -36,6 +26,19 @@ Examples of unacceptable behavior include:
 * Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
 ## Enforcement Responsibilities
 
 Community leaders are responsible for clarifying and enforcing our standards of

ISSUE_134_SUMMARY.md

@@ -1,39 +1,5 @@
 # Issue #134: Backend SSE Stream Updates - COMPLETE ✅
 
-## What Was Built
-
-A production-ready **Server-Sent Events (SSE)** system for real-time stream updates in FlowFi.
-
-## Key Decisions
-
-### SSE vs WebSockets
-**Chose SSE** for:
-- Unidirectional updates (server → client)
-- Simpler implementation & debugging
-- Automatic browser reconnection
-- Better HTTP/2 compatibility
-- Lower overhead for broadcasting
-
-## Implementation Summary
-
-### Core Files Created (7)
-```
-backend/src/
-├── services/sse.service.ts              # SSE connection manager
-├── controllers/sse.controller.ts        # Subscription endpoint
-└── routes/events.routes.ts              # /events routes
-
-backend/
-├── docs/
-│   ├── SSE_IMPLEMENTATION.md            # Full guide
-│   └── SSE_ARCHITECTURE.md              # Architecture diagrams
-├── examples/useStreamEvents.tsx         # React hook
-└── test-sse-client.html                 # Test client
-```
-
-### Files Modified (2)
-- `src/app.ts` - Added events routes
-- `src/controllers/stream.controller.ts` - Added broadcasting
 
 ## API Endpoints
 
@@ -205,3 +171,39 @@ Blockchain → Backend → SSE Service → Multiple Clients
 ✅ **Secure** with documented best practices  
 
 **Ready for integration with blockchain indexer and frontend.**
+
+
+## What Was Built
+
+A production-ready **Server-Sent Events (SSE)** system for real-time stream updates in FlowFi.
+
+## Key Decisions
+
+### SSE vs WebSockets
+**Chose SSE** for:
+- Unidirectional updates (server → client)
+- Simpler implementation & debugging
+- Automatic browser reconnection
+- Better HTTP/2 compatibility
+- Lower overhead for broadcasting
+
+## Implementation Summary
+
+### Core Files Created (7)
+```
+backend/src/
+├── services/sse.service.ts              # SSE connection manager
+├── controllers/sse.controller.ts        # Subscription endpoint
+└── routes/events.routes.ts              # /events routes
+
+backend/
+├── docs/
+│   ├── SSE_IMPLEMENTATION.md            # Full guide
+│   └── SSE_ARCHITECTURE.md              # Architecture diagrams
+├── examples/useStreamEvents.tsx         # React hook
+└── test-sse-client.html                 # Test client
+```
+
+### Files Modified (2)
+- `src/app.ts` - Added events routes
+- `src/controllers/stream.controller.ts` - Added broadcasting

README.md

@@ -29,6 +29,18 @@ flowfi/
 │   └── DEVELOPMENT.md    # Local development guide
 ```
 
+
+
+For full step-by-step instructions, see our [Development Guide](docs/DEVELOPMENT.md).
+
+### Prerequisites
+
+- Node.js & npm
+- Rust & Cargo
+- Stellar CLI (optional but recommended)
+- Docker & Docker Compose (for containerized setup)
+
+
 ## Architecture
 
 FlowFi consists of three main components that work together:
@@ -43,14 +55,6 @@ For full local setup and contributor onboarding, see the [Development Guide](doc
 
 ## Getting Started
 
-For full step-by-step instructions, see our [Development Guide](docs/DEVELOPMENT.md).
-
-### Prerequisites
-
-- Node.js & npm
-- Rust & Cargo
-- Stellar CLI (optional but recommended)
-- Docker & Docker Compose (for containerized setup)
 
 ### Docker (Recommended)
 
@@ -83,18 +87,19 @@ To reset the database:
 docker compose down -v
 ```
 
-### Backend (Manual)
+
+
+### Frontend
 
 ```bash
-cd backend
+cd frontend
 npm install
 npm run dev
 ```
-
-### Frontend
+### Backend (Manual)
 
 ```bash
-cd frontend
+cd backend
 npm install
 npm run dev
 ```

backend/README.md

@@ -19,15 +19,37 @@ DATABASE_URL=postgresql://user:password@localhost:5433/flowfi?schema=public
 PORT=3001
 STELLAR_RPC_URL=https://soroban-testnet.stellar.org
 NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+API_BASE_URL=https://api.staging.flowfi.io
 ```
 
+- `API_BASE_URL`: Overrides the Swagger UI server URL for the deployed environment (e.g., staging or production). When set, Swagger UI targets `<API_BASE_URL>/v1` instead of the hardcoded defaults.
+
 ## Prisma Database
 
 We use Prisma as our ORM to interact with PostgreSQL.
 
 - Schema is located at `prisma/schema.prisma`.
+- Configuration (schema path, migrations path, datasource URL) is defined in `prisma.config.ts`.
 - Run `npx prisma studio` to view the database through a web UI.
 
+### Seeding the database
+
+`prisma/seed.ts` populates the database with demo fixtures for local development. Run it with:
+
+```bash
+npm run prisma:seed
+```
+
+(this runs `prisma db seed`, which in turn runs `tsx prisma/seed.ts` as configured under the `prisma.seed` key in `package.json`.)
+
+The script is idempotent (it uses `upsert`/fixed IDs), so it's safe to run multiple times. It creates:
+
+- Two demo users, keyed by fixed Stellar testnet public keys — a sender (`GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN`) and a recipient (`GBJCHUKZMTFSLOMNC7P4TS4VJJBTCYL3XKSOLXAUJSD56C4LHND5TWUC`).
+- One demo `Stream` (`streamId: 101`) between those two users, using a fixed demo token address, with a sample rate/deposit amount and `isActive: true`.
+- One demo `StreamEvent` (`eventType: 'CREATED'`) attached to that stream, with sample transaction hash, ledger sequence, and metadata.
+
+These fixtures are intended purely for local development/demo purposes so the frontend has data to render out of the box; they are not used in automated tests.
+
 ## /v1 API
 
 All REST API endpoints are prefixed with `/v1`. Refer to the API Documentation in the root `README.md` and the `docs/` folder for versioning and authentication details.

backend/prisma/migrations/20260630120000_add_stream_event_stream_id_timestamp_index/migration.sql

@@ -0,0 +1,8 @@
+-- Replace the unused (streamId, createdAt) composite with (streamId, timestamp),
+-- which matches streamId-scoped event listings that ORDER BY timestamp.
+
+-- CreateIndex
+CREATE INDEX IF NOT EXISTS "StreamEvent_streamId_timestamp_idx" ON "StreamEvent"("streamId", "timestamp");
+
+-- DropIndex
+DROP INDEX IF EXISTS "StreamEvent_streamId_createdAt_idx";

backend/prisma/migrations/20260727090000_stream_id_bigint/migration.sql

@@ -0,0 +1,12 @@
+-- Convert on-chain stream identifiers from int4 to bigint (Soroban u64).
+-- Drop the FK first so both columns can be widened, then recreate it.
+
+ALTER TABLE "StreamEvent" DROP CONSTRAINT IF EXISTS "StreamEvent_streamId_fkey";
+
+ALTER TABLE "Stream" ALTER COLUMN "streamId" TYPE BIGINT USING ("streamId"::bigint);
+ALTER TABLE "StreamEvent" ALTER COLUMN "streamId" TYPE BIGINT USING ("streamId"::bigint);
+
+ALTER TABLE "StreamEvent"
+  ADD CONSTRAINT "StreamEvent_streamId_fkey"
+  FOREIGN KEY ("streamId") REFERENCES "Stream"("streamId")
+  ON DELETE RESTRICT ON UPDATE CASCADE;

backend/prisma/migrations/20260729170000_timestamp_bigint/migration.sql

@@ -0,0 +1,8 @@
+-- AlterTable
+ALTER TABLE "Stream" ALTER COLUMN "startTime" SET DATA TYPE BIGINT,
+ALTER COLUMN "lastUpdateTime" SET DATA TYPE BIGINT,
+ALTER COLUMN "endTime" SET DATA TYPE BIGINT,
+ALTER COLUMN "pausedAt" SET DATA TYPE BIGINT;
+
+-- AlterTable
+ALTER TABLE "StreamEvent" ALTER COLUMN "timestamp" SET DATA TYPE BIGINT;

backend/prisma/schema.prisma

@@ -27,19 +27,19 @@ model User {
 // Stream model - mirrors on-chain stream state for fast querying
 model Stream {
   id                String    @id @default(uuid())
-  streamId          Int       @unique // On-chain stream ID
+  streamId          BigInt    @unique // On-chain stream ID (Soroban u64)
   sender            String    // Sender's Stellar public key
   recipient         String    // Recipient's Stellar public key
   tokenAddress      String    // Token contract address
   ratePerSecond     String    // Rate as string to preserve precision (i128)
   depositedAmount   String    // Total deposited amount (i128)
   withdrawnAmount   String    // Total withdrawn amount (i128)
-  startTime         Int       // Unix timestamp when stream started
-  lastUpdateTime    Int       // Unix timestamp of last update
-  endTime           Int?      // Unix timestamp when stream ends
+  startTime         BigInt    // Unix timestamp when stream started
+  lastUpdateTime    BigInt    // Unix timestamp of last update
+  endTime           BigInt?   // Unix timestamp when stream ends
   isActive          Boolean   @default(true)
   isPaused          Boolean   @default(false)
-  pausedAt          Int?      // Unix timestamp when paused
+  pausedAt          BigInt?   // Unix timestamp when paused
   totalPausedDuration Int     @default(0) // Accumulated paused duration in seconds
   createdAt         DateTime  @default(now())
   updatedAt         DateTime  @updatedAt
@@ -68,12 +68,12 @@ model IndexerState {
 // StreamEvent model - indexer events for tracking all on-chain stream activities
 model StreamEvent {
   id              String   @id @default(uuid())
-  streamId        Int      // Reference to on-chain stream ID
+  streamId        BigInt   // Reference to on-chain stream ID (Soroban u64)
   eventType       String   // EventType: "CREATED", "TOPPED_UP", "WITHDRAWN", "CANCELLED", "COMPLETED", "PAUSED", "RESUMED"
   amount          String?  // Amount involved in the event (for top-ups, withdrawals)
   transactionHash String   // Stellar transaction hash
   ledgerSequence  Int      // Ledger sequence number
-  timestamp       Int      // Unix timestamp
+  timestamp       BigInt   // Unix timestamp
   metadata        String?  // JSON string for additional event data
   createdAt       DateTime @default(now())
 
@@ -86,5 +86,6 @@ model StreamEvent {
   @@index([timestamp])
   @@index([transactionHash])
   @@index([createdAt])
-  @@index([streamId, createdAt])
+  @@index([streamId, timestamp])
+  @@unique([transactionHash, eventType])
 }

backend/src/app.ts

@@ -16,6 +16,7 @@ import { requestIdMiddleware } from "./middleware/requestId.js";
 import v1Routes from "./routes/v1/index.js";
 
 import healthRoutes from "./routes/health.routes.js";
+import "./lib/stream-id.js";
 
 const app = express();
 const isProduction = process.env.NODE_ENV === "production";

backend/src/config/swagger.ts

@@ -37,16 +37,16 @@ See [Sandbox Mode Documentation](../docs/SANDBOX_MODE.md) for details.`,
         url: 'https://opensource.org/licenses/MIT',
       },
     },
-    servers: [
-      {
-        url: 'http://localhost:3001/v1',
-        description: 'Development server (v1)',
-      },
-      {
-        url: 'https://api.flowfi.io/v1',
-        description: 'Production server (v1)',
-      },
-    ],
+    servers: (() => {
+      const baseUrl = process.env.API_BASE_URL;
+      if (baseUrl) {
+        return [{ url: `${baseUrl}/v1`, description: 'API server' }];
+      }
+      return [
+        { url: 'http://localhost:3001/v1', description: 'Development server (v1)' },
+        { url: 'https://api.flowfi.io/v1', description: 'Production server (v1)' },
+      ];
+    })(),
     tags: [
       {
         name: 'Health',