How akash2xd/blood_donation_system works
1. Overall shape
- LifeLink is a single-page React application built with Vite and TypeScript.
- The UI talks directly to Supabase for auth, database access, realtime data, and storage; there is no custom Node backend in this repo.
- Architecture is therefore “frontend-heavy, database-driven,” with a large part of the business logic implemented in PostgreSQL functions, triggers, and RLS policies.
2. Primary user roles and boundaries
- The app is organized around three core actor types: donors, hospitals, and blood banks.
- Each role has its own registration and dashboard flows, plus shared features such as notifications, chat, and location-based discovery.
- The role boundary is enforced both in React routing/components and in Supabase policies and schema.
3. Frontend application shell
- src/main.tsx and src/App.tsx boot the app.
- Common layout/navigation is handled by shared components such as Layout, NavBar, Footer, Navigation, and ActionBanner.
- Pages under src/pages map to the main product areas: donor onboarding, emergency requests, dashboards, donation scheduling, blood bank list/dashboard, hospital dashboard, auth pages, and informational content.
4. Feature modules in the UI
- The component tree is organized by domain rather than by technical layer.
- Major feature groups include:
- donor registration and profile (DonorForm, UserProfile, BecomeDonor)
- emergency response (EmergencyRequestForm, EmergencyRequests, EmergencyRequestConfirmation)
- scheduling and booking (SchedulerForm, SchedulerModal, DonationSlotSelector, DonationSchedulerModal)
- blood bank management (BloodBankForm, BloodInventoryManager, BloodBankSlots)
- hospital workflows (HospitalForm, HospitalDashboard, HospitalDonorDistanceMap)
- chat/assistant (Chatbot, AIChatbot, CommunityChat)
- This suggests a modular SPA where each workflow is mostly self-contained at the component level.
5. Core backend datastore
- Supabase/PostgreSQL is the system of record.
- Main tables called out in the repo are donors, blood_banks, hospitals, blood_inventory, realtime_locations, emergency_requests, donor_responses, scheduled_donations, hospital_donations, notifications, hospital_donation_slots, blood_bank_slots, and community_chat.
- auth.users is the identity root, with profile tables linked to authenticated users through foreign keys and policies.
6. Database-centric business logic
- A significant portion of the product logic lives in SQL migrations and fix scripts rather than in the frontend.
- Repeated fixes for slot booking, donation verification, donor rewards, emergency requests, and hospital dashboard queries indicate that database functions/triggers are central to the architecture.
- The repo contains many corrective migrations, which implies the schema and RPC layer are treated as an application layer, not just storage.
7. Scheduling and slot booking flow
- Donation scheduling is one of the most important end-to-end flows.
- Frontend slot selectors and scheduler modals query available slots from Supabase, then create/update scheduled donation records.
- Backend functions enforce capacity, day-of-week rules, and uniqueness via composite IDs and slot-booking counters.
- Hospital and blood bank slots are modeled separately but unified in the UX.
8. Emergency request workflow
- Emergency requests are created from the frontend and stored in Supabase.
- Donors can respond to requests, generating donor_responses and notifications.
- The app includes confirmation UI and map-based views to support matching and distance-aware selection.
- Policies around request visibility and state transitions are important because the flow is permission-sensitive.
9. Location, maps, and proximity features
- Location is a first-class subsystem.
- The app uses OLA Maps via src/lib/olaMapsApi.ts, map components, and geolocation helpers to support donor discovery and facility mapping.
- Supabase stores realtime location data, while the frontend renders donor/hospital/blood-bank distance and map views.
- This is a key integration boundary between browser geolocation, external mapping APIs, and database queries.
10. Notifications and realtime updates
- notifications is a central cross-cutting table used for scheduling, emergency responses, and verification events.
- Realtime behavior is supported both by Supabase features and by frontend components like NotificationBell.
- Several migrations focus on notification schema and policy fixes, which suggests notifications are not incidental—they are part of the core workflow orchestration.
11. Chat and AI assistant
- The repo has two chat-related layers:
- community/user chat backed by database tables and realtime updates
- AI chatbot backed by Groq API and a chatbot_knowledge table
- chatbotService.ts and groqService.ts sit between UI components and the external LLM API.
- The chatbot can also trigger navigation, so it behaves partly like a guided assistant, not just a Q&A widget.
12. File upload and storage
- Supabase Storage is used for assets such as blood bank license documents and other uploaded verification files.
- Storage policies and bucket configuration are explicitly managed in migrations, indicating that uploads are permission-sensitive and tightly integrated with registration/verification flows.
13. Auth, policies, and security boundary
- Supabase Auth handles sign-in/sign-up, while Row Level Security governs what each role can read or mutate.
- There are many migrations for policy fixes, trigger conflicts, and user/profile consistency, showing that security is enforced primarily at the database layer.
- The frontend assumes those policies exist and surfaces the role-specific UI accordingly.
14. Schema evolution and operational tooling
- The repository includes a large number of timestamped migrations plus many ad hoc SQL repair scripts at the repo root.
- There is also run_migration_fix.js, Supabase CLI configuration, and direct SQL scripts for emergency repair.
- For architecture diagram purposes, this means the database is not static infrastructure; it is an actively evolved subsystem with both formal migrations and manual recovery paths.
15. Testing and quality gates
- The repo includes lightweight tests for form workflows and slot booking logic under src/__tests__.
- These tests appear focused on critical user flows rather than broad unit coverage, which aligns with the domain-heavy UI and SQL-heavy backend design.
- Build/lint tooling is standard Vite/TypeScript/Tailwind/ESLint, with deployment configuration for hosting and routing.
16. How data typically flows
- A user authenticates through Supabase Auth.
- The React UI loads role-specific profile and domain data from Supabase tables.
- User actions such as registering, scheduling a donation, responding to an emergency request, or verifying a donation invoke Supabase queries/functions.
- Database triggers/functions update related tables, notifications, rewards, and slot counts.
- The UI then reflects the updated state through direct refresh, realtime subscriptions, or re-querying.
Main entry points: database.types.ts Core Tables · supabase.ts Supabase Client · pages Role Pages · 20250316110000_add_donation_triggers.sql Triggers & Rewards
Components 19
Frontend SPA
React/Vite application and user-facing workflows
- Main · App bootstrap and runtime entrypoint
src/main.tsx - App Shell · Top-level routing and application composition
src/App.tsx - Layout · Shared navigation, banner, and page chrome
src/components/Layout.tsx - Role Pages · Route-level donor, hospital, blood bank, auth, and info screens
src/pages - Domain Forms · Registration, scheduling, request, and verification components
src/components - Maps & Location · Geolocation, map views, and proximity helpers
src/lib/geolocation.ts - Chat UI · Community chat and AI assistant components
src/components/Chatbot.tsx - Notifications · Notification bell and UI refresh surfaces
src/components/NotificationBell.tsx
Supabase Backend
Auth, tables, functions, policies, realtime, and storage
- Supabase Client · Browser-side access to auth, database, realtime, and storage
src/lib/supabase.ts - Auth & Profiles · Auth users plus donor, hospital, and blood bank profile records
supabase/migrations/20240317000006_create_profiles.sql - Core Tables · Donors, facilities, requests, donations, chat, locations, and notifications
src/lib/database.types.ts - Scheduling Logic · Slot capacity, booking, and donation scheduling rules
supabase/migrations/20250317000002_add_scheduler_tables.sql - Emergency Workflow · Request creation, donor responses, matching, and status transitions
supabase/migrations/20240317000002_create_emergency_requests.sql - Location Services · Nearby donor search and realtime location updates
supabase/migrations/20250401000000_add_realtime_locations.sql - Chat Backend · Community chat tables and chatbot knowledge base
supabase/migrations/20250401005000_add_community_chat.sql - Storage & RLS · Storage buckets, permissions, and row-level security policies
supabase/migrations/20250401030000_fix_storage_buckets.sql - Triggers & Rewards · Triggers, verification updates, notifications, and donor reward side effects
supabase/migrations/20250316110000_add_donation_triggers.sql
Schema Ops
Migrations, repair scripts, and database recovery tooling
- Migrations · Long-running schema evolution and repair history
supabase/migrations - Repair Scripts · Ad hoc SQL fixes and migration recovery helpers
fix_database.sql
Connections 24
- Main → App Shell: bootstraps · Application entry loads the router and providers
- App Shell → Layout: wraps · Routes are rendered inside shared chrome
- App Shell → Role Pages: routes to · Top-level pages define the product surface
- Role Pages → Domain Forms: uses · Pages embed workflow-specific forms and modals
- Role Pages → Maps & Location: shows · Several pages include maps and location-aware views
- Role Pages → Chat UI: includes · Community and AI assistant surfaces are page-level features
- Role Pages → Notifications: surfaces · Pages and dashboards reflect notification state
- Domain Forms → Supabase Client: queries · Forms read and write directly through the client
- Maps & Location → Supabase Client: reads/writes · Location features persist and fetch data through Supabase
- Chat UI → Supabase Client: subscribes · Chat uses database-backed realtime data and assistant services
- Notifications → Supabase Client: subscribes · Notifications are driven by realtime/db state
- Supabase Client → Auth & Profiles: authenticates · Client uses Supabase Auth and profile tables
- Supabase Client → Core Tables: accesses · Primary application data is stored in domain tables
- Core Tables → Scheduling Logic: drives · Slot records and bookings are enforced by SQL logic
- Core Tables → Emergency Workflow: drives · Emergency requests and responses are coordinated in SQL
- Core Tables → Location Services: drives · Realtime locations and nearby search depend on SQL functions
- Core Tables → Chat Backend: drives · Community chat and chatbot knowledge are database-backed
- Scheduling Logic → Triggers & Rewards: updates · Scheduling changes cascade into confirmations and counts
- Emergency Workflow → Triggers & Rewards: updates · Request responses create notifications and state changes
- Location Services → Triggers & Rewards: updates · Location refreshes and visibility rules can trigger side effects
- Storage & RLS → Auth & Profiles: guards · Policies tie uploads and records to authenticated roles
- Migrations → Core Tables: evolves · Schema history defines and repairs the data model
- Repair Scripts → Migrations: patches · Manual SQL scripts complement formal migrations
- Repair Scripts → Triggers & Rewards: fixes · Ad hoc fixes often target broken functions and triggers