docs: verify indexer database schema matches architecture requirements

Author: Prz-droid

indexer/DATABASE_SCHEMA_VERIFICATION.md

@@ -0,0 +1,107 @@
+# Database Schema Verification
+
+## Status: ✅ COMPLETE
+
+All database entities, migrations, and indexes are already implemented and match the ARCHITECTURE.md requirements.
+
+## Entities Implemented
+
+### 1. RaffleEntity (`raffles` table)
+- ✅ All required columns: id, creator, status, ticket_price, asset, max_tickets, tickets_sold, end_time, winner, prize_amount, created_ledger, finalized_ledger, metadata_cid, created_at
+- ✅ Indexes: status, creator, created_at
+- ✅ Relationships: OneToMany with tickets and events
+- ✅ Enum: RaffleStatus (OPEN, DRAWING, FINALIZED, CANCELLED)
+
+### 2. TicketEntity (`tickets` table)
+- ✅ All required columns: id, raffle_id, owner, purchased_at_ledger, purchase_tx_hash, refunded, refund_tx_hash
+- ✅ Indexes: raffle_id, owner, purchase_tx_hash (unique)
+- ✅ Relationships: ManyToOne with raffle
+- ✅ Idempotency: purchase_tx_hash unique constraint
+
+### 3. UserEntity (`users` table)
+- ✅ All required columns: address (PK), total_tickets_bought, total_raffles_entered, total_raffles_won, total_prize_xlm, first_seen_ledger, updated_at
+- ✅ Natural primary key: address (Stellar account)
+- ✅ Aggregated statistics for leaderboard queries
+
+### 4. RaffleEventEntity (`raffle_events` table)
+- ✅ All required columns: id, raffle_id, event_type, ledger, tx_hash, payload_json, indexed_at
+- ✅ Indexes: raffle_id, event_type, tx_hash (unique)
+- ✅ JSONB payload for flexible event data storage
+- ✅ Audit trail and idempotency via tx_hash
+
+### 5. PlatformStatEntity (`platform_stats` table)
+- ✅ All required columns: date (PK), total_raffles, total_tickets, total_volume_xlm, unique_participants, prizes_distributed_xlm
+- ✅ Daily aggregates for analytics
+- ✅ Natural primary key: date
+
+### 6. IndexerCursorEntity (`indexer_cursor` table)
+- ✅ All required columns: id (singleton PK=1), last_ledger, last_paging_token, updated_at
+- ✅ Singleton pattern for resumable indexing
+- ✅ Crash-safe restart capability
+
+### 7. WebhookEntity (`webhooks` table)
+- ✅ Additional entity for webhook management
+- ✅ Not in original ARCHITECTURE but useful for notifications
+
+## Migrations
+
+All migrations are present in `src/database/migrations/`:
+
+1. ✅ `1700000000000-CreateRaffles.ts` - Creates raffles table with indexes
+2. ✅ `1700000000001-CreateTickets.ts` - Creates tickets table with indexes
+3. ✅ `1700000000002-CreateUsers.ts` - Creates users table
+4. ✅ `1700000000003-CreateRaffleEvents.ts` - Creates raffle_events table
+5. ✅ `1700000000004-CreatePlatformStats.ts` - Creates platform_stats table
+6. ✅ `1700000000005-CreateIndexerCursor.ts` - Creates indexer_cursor table
+7. ✅ `1700000000006-CreatePlatformState.ts` - Creates platform_state table
+8. ✅ `1720000000000-AddWebhooksTable.ts` - Creates webhooks table
+
+## Key Features
+
+### Indexes for Performance
+- ✅ `idx_raffles_status` - Fast filtering by raffle status
+- ✅ `idx_raffles_creator` - Fast lookup by creator address
+- ✅ `idx_raffles_created_at` - Time-based queries
+- ✅ `idx_tickets_raffle_id` - Fast ticket lookup by raffle
+- ✅ `idx_tickets_owner` - Fast user ticket history
+- ✅ `idx_tickets_purchase_tx_hash` - Unique constraint for idempotency
+- ✅ `idx_raffle_events_raffle_id` - Event history by raffle
+- ✅ `idx_raffle_events_event_type` - Event filtering
+- ✅ `idx_raffle_events_tx_hash` - Unique constraint for idempotency
+
+### Data Integrity
+- ✅ Unique constraints on transaction hashes prevent duplicate indexing
+- ✅ Foreign key relationships with CASCADE delete
+- ✅ String storage for large numbers (stroops) to avoid JS integer overflow
+- ✅ JSONB for flexible event payload storage
+- ✅ Enum types for status fields
+
+### Resilience
+- ✅ Idempotent upserts via unique tx_hash constraints
+- ✅ Resumable indexing via cursor persistence
+- ✅ Automatic migrations on app bootstrap (`migrationsRun: true`)
+
+## Database Setup Documentation
+
+The README.md includes comprehensive documentation:
+- ✅ Environment variable configuration
+- ✅ Local Postgres setup with Docker
+- ✅ Migration commands
+- ✅ Data model overview
+- ✅ Redis cache TTL strategy
+- ✅ Health endpoint specification
+
+## TypeORM Configuration
+
+`src/data-source.ts` properly configured with:
+- ✅ All entities registered
+- ✅ Migrations path configured
+- ✅ SSL support for production (Supabase/Railway)
+- ✅ Environment variable support (DATABASE_URL or individual vars)
+- ✅ Logging enabled for debugging
+
+## Conclusion
+
+The indexer database schema is production-ready and fully compliant with the ARCHITECTURE.md specification. All required tables, columns, indexes, and relationships are implemented with proper TypeORM entities and migrations.
+
+No additional work is needed for this task.