Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
512 lines (456 loc) · 20.3 KB

ARCHITECTURE.md

File metadata and controls

512 lines (456 loc) · 20.3 KB
Raw

Habiqua Student Hub Platform - Architecture Documentation

System Architecture Overview

``` ┌────────────────────────────────────────────────────────────────┐ │ CLIENT (Browser) │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ React Application (Vite) │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ Public │ │ Auth │ │ Dashboard │ │ │ │ │ │ Portal │ │ Pages │ │ (Owner) │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ │ │ React Router (Navigation) │ │ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ │ │ Auth Context (Global State) │ │ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ │ │ Service Layer │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │ │ │ │ │ │ Auth │ │ Room │ │ Storage │ │ │ │ │ │ │ │ Service │ │ Service │ │ Service │ │ │ │ │ │ │ └──────────┘ └──────────┘ └────────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ │ │ └────────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ │ │ HTTPS ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Firebase Backend (Serverless) │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ │ │ Authentication │ │ Firestore │ │ Storage │ │ │ │ │ │ Database │ │ (Images) │ │ │ │ • Email/Pass │ │ │ │ │ │ │ │ • Google OAuth │ │ Collection: │ │ /rooms/ │ │ │ │ • JWT Tokens │ │ - rooms │ │ {id}/ │ │ │ │ │ │ │ │ *.jpg │ │ │ └──────────────────┘ └──────────────────┘ └──────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Security Rules Engine │ │ │ │ • Firestore Rules • Storage Rules │ │ │ └────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ```

Application Flow Diagrams

1. User Authentication Flow

``` ┌─────────┐ │ User │ └────┬────┘ │ ├─ Visit /login │ ▼ ┌─────────────────┐ │ Login Page │ └────┬────┬───────┘ │ │ │ └─ Google OAuth │ │ │ ▼ │ ┌──────────────────┐ │ │ Google Sign-In │ │ │ Popup │ │ └────┬─────────────┘ │ │ ├─────────┴─ Firebase Auth │ ▼ ┌──────────────────┐ │ Auth Context │ │ (Sets user state)│ └────┬─────────────┘ │ ▼ ┌──────────────────┐ │ Protected Route │ │ Redirect to │ │ /dashboard │ └──────────────────┘ ```

2. Room Creation Flow

``` ┌────────────┐ │ Owner │ │ Dashboard │ └─────┬──────┘ │ ├─ Click "Add New Room" │ ▼ ┌─────────────────┐ │ Room Form │ │ Modal │ └────┬────────────┘ │ ├─ Fill form data ├─ Select images ├─ Submit │ ▼ ┌─────────────────────┐ │ Room Service │ │ createRoom() │ └────┬────────────────┘ │ ├─ 1. Create Firestore doc │ (get roomId) │ ├─ 2. Upload images │ to Storage │ (/rooms/{roomId}/) │ ├─ 3. Update Firestore doc │ with image URLs │ ▼ ┌─────────────────────┐ │ Success Toast │ │ Refresh Room List │ └─────────────────────┘ ```

3. Room Search Flow

``` ┌──────────────┐ │ Public User │ └──────┬───────┘ │ ├─ Visit /search │ ▼ ┌──────────────────┐ │ Search Page │ │ - Search Bar │ │ - Filters │ └────┬─────────────┘ │ ├─ Enter search criteria ├─ Apply filters │ ▼ ┌──────────────────────┐ │ useRooms Hook │ │ searchRooms() │ └────┬─────────────────┘ │ ▼ ┌──────────────────────┐ │ Room Service │ │ - Fetch from │ │ Firestore │ │ - Apply client-side │ │ filtering │ └────┬─────────────────┘ │ ▼ ┌──────────────────────┐ │ Room Grid │ │ Display results │ └────┬─────────────────┘ │ ├─ Click room card │ ▼ ┌──────────────────────┐ │ Room Detail Modal │ │ - Image carousel │ │ - Full details │ │ - Contact owner │ └──────────────────────┘ ```

Component Hierarchy

``` App (AuthProvider) │ └── RouterProvider │ └── Root (Layout) ├── Header (Navigation) │ ├── Outlet (Page Content) │ │ │ ├── Home │ │ ├── HeroSection │ │ ├── AboutSection │ │ └── FeaturesSection │ │ │ ├── SearchRooms │ │ ├── SearchBar │ │ ├── FilterPanel │ │ ├── RoomGrid │ │ │ └── RoomCard (multiple) │ │ └── RoomDetailModal │ │ │ ├── Login │ │ ├── LoginForm │ │ └── GoogleSignIn │ │ │ ├── Dashboard (Protected) │ │ ├── Stats Cards │ │ ├── RoomList │ │ │ └── Room Items │ │ └── RoomForm (Modal) │ │ └── ImageUploader │ │ │ └── NotFound │ └── Footer ```

Data Flow Architecture

State Management Strategy

``` ┌──────────────────────────────────────────────────────┐ │ Global State (Context) │ │ │ │ AuthContext │ │ ├── user: User | null │ │ ├── loading: boolean │ │ └── onAuthStateChanged listener │ └──────────────────────────────────────────────────────┘ │ │ Provides to ▼ ┌──────────────────────────────────────────────────────┐ │ Component State (Local) │ │ │ │ useState hooks for: │ │ ├── Form inputs │ │ ├── Modal visibility │ │ ├── Loading states │ │ └── Error messages │ └──────────────────────────────────────────────────────┘ │ │ Calls ▼ ┌──────────────────────────────────────────────────────┐ │ Custom Hooks │ │ │ │ useRooms(filters?) │ │ ├── rooms: Room[] │ │ ├── loading: boolean │ │ ├── error: string | null │ │ └── refetch() │ │ │ │ useOwnerRooms(ownerId) │ │ ├── rooms: Room[] │ │ ├── loading: boolean │ │ └── refetch() │ └──────────────────────────────────────────────────────┘ │ │ Uses ▼ ┌──────────────────────────────────────────────────────┐ │ Service Layer │ │ │ │ authService │ │ ├── login() │ │ ├── register() │ │ ├── loginWithGoogle() │ │ └── logout() │ │ │ │ roomService │ │ ├── createRoom() │ │ ├── updateRoom() │ │ ├── deleteRoom() │ │ ├── getAllRooms() │ │ ├── searchRooms() │ │ └── getRoomsByOwner() │ │ │ │ storageService │ │ ├── uploadImages() │ │ └── deleteImage() │ └──────────────────────────────────────────────────────┘ │ │ Interacts with ▼ ┌──────────────────────────────────────────────────────┐ │ Firebase SDK │ │ │ │ ├── firebase/auth │ │ ├── firebase/firestore │ │ └── firebase/storage │ └──────────────────────────────────────────────────────┘ ```

Security Architecture

Authentication Flow

```

  1. User Login/Register ↓
  2. Firebase Auth validates credentials ↓
  3. JWT token generated ↓
  4. Token stored in browser (httpOnly cookie) ↓
  5. Token sent with each request ↓
  6. Firebase SDK validates token ↓
  7. Access granted/denied based on rules ```

Firestore Security Rules Logic

```javascript // Read: Anyone can view rooms allow read: if true;

// Create: Must be authenticated + ownerId matches auth UID allow create: if request.auth != null && request.resource.data.ownerId == request.auth.uid;

// Update/Delete: Must be the owner allow update, delete: if request.auth != null && resource.data.ownerId == request.auth.uid; ```

Storage Security Rules Logic

```javascript // Read: Anyone can view images allow read: if true;

// Write: Must be authenticated allow write: if request.auth != null; ```

Performance Optimizations

1. Code Splitting

  • React Router automatically splits routes
  • Each page is a separate bundle
  • Loaded on-demand when user navigates

2. Image Optimization

  • Firebase Storage CDN delivery
  • Automatic format optimization
  • Lazy loading with ImageWithFallback component

3. Query Optimization

  • Firestore compound indexes (auto-created)
  • Client-side caching via React state
  • Pagination ready (not implemented by default)

4. Build Optimization

  • Vite's optimized production builds
  • Tree-shaking removes unused code
  • Minification and compression

Scalability Considerations

Current Implementation

  • Good for: 1-10K users, 100-1K rooms
  • Limitations: Client-side filtering, no pagination

Scaling Recommendations

For 10K+ users:

  1. Implement pagination (Firestore cursors)
  2. Add Algolia for advanced search
  3. Implement Redis caching layer
  4. Use Cloud Functions for complex operations

For 100K+ users:

  1. Consider migrating to Cloud Firestore collections with better indexing
  2. Implement CDN for static assets
  3. Add load balancing
  4. Implement rate limiting

For 1M+ users:

  1. Consider microservices architecture
  2. Separate read/write databases
  3. Implement event-driven architecture
  4. Add analytics and monitoring

Technology Decisions

Why Firebase?

  • ✅ Serverless (no backend management)
  • ✅ Real-time capabilities
  • ✅ Built-in authentication
  • ✅ Free tier generous enough for MVP
  • ✅ Scales automatically
  • ❌ Vendor lock-in concern
  • ❌ Complex queries limited

Why React?

  • ✅ Component reusability
  • ✅ Large ecosystem
  • ✅ Virtual DOM performance
  • ✅ TypeScript support
  • ✅ Great developer experience

Why Vite?

  • ✅ Fast HMR (Hot Module Replacement)
  • ✅ Optimized production builds
  • ✅ Modern ESM support
  • ✅ Better than CRA

Why TailwindCSS?

  • ✅ Utility-first approach
  • ✅ Consistent design system
  • ✅ Small production bundle
  • ✅ No runtime CSS-in-JS overhead
  • ✅ Easy responsive design

Deployment Architecture

Firebase Hosting

``` User Request ↓ Firebase CDN (Edge locations worldwide) ↓ Serves cached HTML/CSS/JS ↓ Browser executes React app ↓ Calls Firebase APIs (Auth, Firestore, Storage) ```

Alternative: Vercel/Netlify

``` User Request ↓ Vercel/Netlify Edge Network ↓ Serves static files from CDN ↓ Browser executes React app ↓ Calls Firebase APIs (same as above) ```

Monitoring & Analytics

Recommended Implementation

  1. Firebase Analytics

    • User engagement metrics
    • Screen view tracking
    • Custom events (room views, searches)

  2. Performance Monitoring

    • Page load times
    • API response times
    • Error tracking

  3. Crashlytics (for mobile apps)

    • Crash reports
    • User diagnostics

  4. Cloud Monitoring

    • Firestore usage
    • Storage bandwidth
    • Authentication metrics

Future Architecture Improvements

Phase 1: Enhanced Search

  • Algolia integration for full-text search
  • Geographic search with maps
  • Fuzzy matching for typos

Phase 2: Real-time Features

  • Live chat between users and owners
  • Real-time availability updates
  • Push notifications

Phase 3: Advanced Features

  • Payment processing (Stripe)
  • Booking system with calendar
  • Review and rating system
  • Admin dashboard

Phase 4: Mobile Apps

  • React Native mobile app
  • Shared codebase with web
  • Push notifications
  • Offline support

Architecture Version: 1.0
Last Updated: February 2026
Maintained By: Development Team