1. SYSTEM OVERVIEW

1.1 Purpose

Dual-mode whistleblowing platform:

• Anonymous Mode: Blockchain-stored with public pseudonym (IMMUTABLE - cannot edit/delete)
• Identified Mode: Database-stored with identity visible to admins (CAN edit/delete)

1.2 Core Architecture

• Single account system (email/password)
• Auto-generated anonymous identifier per user
• User selects mode per complaint
• Encrypted identity-to-pseudonym mapping

1.3 Technology Stack

Frontend:

├── Web: React 19, TailwindCSS, TypeScript
├── State: React Query (TanStack),
└── Mobile: Expo / React Native

Backend:
├── Runtime: Bun
├── Framework: Elysia.js
├── Language: TypeScript
└── Jobs: Bull Queue (Redis-backed)

Database:
├── Primary: PostgreSQL
├── Cache: Redis 7 (for sessions, rate limiting, job queue)
└── Search: PostgreSQL Full-Text Search (tsvector)

Blockchain:
├── Network: Hedera
├── SDK: @hashgraph/sdk
└── Service: HCS (Consensus Service)

File Storage:
├── Anonymous: IPFS via Web3.Storage (free)
└── Identified: Supabase Storage (free tier)

Authentication:
├── JWT (access + refresh tokens)
├── Password: bcrypt (cost: 12)
└── Admin: Same as regular users but with admin role

Background Jobs:
├── Queue: Bull (Redis)
└── Scheduler: node-cron

Redis Usage:
├── Session storage (JWT refresh tokens)
├── Rate limiting counters
├── Bull queue for background jobs (HCS indexer ...)

1.4 File Structure (Not Final)

project-root/
├── frontend/
│   ├── app/
│   │   ├── (auth)/
│   │   │   ├── login/
│   │   │   └── signup/
│   │   ├── dashboard/
│   │   │   ├── submit/              # Mode selection + forms
│   │   │   ├── my-complaints/
│   │   │   │   ├── anonymous/
│   │   │   │   └── identified/
│   │   │   └── profile/
│   │   ├── admin/
│   │   │   ├── anonymous/
│   │   │   ├── identified/
│   │   ├── public/
│   │   │   ├── browse/              # Public complaint browsing
│   │   │   ├── complaint/[hash]/
│   │   └── layout.tsx
│   ├── components/
│   │   ├── ui/
│   │   ├── forms/
│   │   └── layouts/
│   └── lib/
│       ├── api.ts
│       └── utils.ts
│
├── backend/
│   ├── src/
│   │   ├── routes/
│   │   │   ├── auth.routes.ts
│   │   │   ├── complaint.routes.ts
│   │   │   ├── admin.routes.ts
│   │   │   └── public.routes.ts
│   │   ├── controllers/
│   │   ├── services/
│   │   │   ├── hedera.service.ts
│   │   │   ├── ipfs.service.ts
│   │   │   └── indexer.service.ts
│   │   ├── middleware/
│   │   │   ├── auth.middleware.ts
│   │   │   ├── validation.middleware.ts
│   │   │   └── rateLimit.middleware.ts
│   │   ├── jobs/
│   │   │   ├── hcs-indexer.job.ts
│   │   └── server.ts
│   ├── prisma/
│   │   └── schema.prisma
│   └── package.json
│
└── README.md

2. FUNCTIONAL REQUIREMENTS

2.1 User Authentication & Profile

User Registration:

• Register with email and password
• Email valid format and unique
• Password min 8 chars: uppercase, lowercase, number, special char
• System auto-generates anonymous_identifier: anon_{12-char-hex}
• Generated: SHA256(user_id + platform_secret)[0:12]
• Unique, cannot be changed
• Send email verification link (valid 24 hours)
• Cannot submit complaints until email verified
• Can resend verification (max 3/hour)
• Store passwords as bcrypt hash (cost: 12)

User Login:

• Authenticate with email/password
• Case-insensitive email
• Generic error for invalid credentials (no user enumeration)
• Lock account after 5 failed attempts
• Issue JWT tokens:
• Access token: 1 hour expiry
• Refresh token: 7 days expiry (stored in Redis)
• Include: user_id, email, anonymous_identifier, role
• Rate limiting:
• Login: 10/min per IP
• Signup: 5/hour per IP
• Log all auth events (login success/failure, signup, password reset)

Profile Management:

• View profile: email, anonymous_identifier, name, phone, created_at
• Update: name, phone (optional fields)
• Cannot update: email, anonymous_identifier
• Change password (requires current password, invalidates all sessions)

Password Recovery:

• Submit email → receive reset link
• Token valid 1 hour, single-use
• Invalidate all sessions on reset