Skip to main content

FURSA HUB - SYSTEM ARCHITECTURE

Version: 1.0
Date: December 2024
Prepared by: Josh

1. EXECUTIVE SUMMARY

Fursa Hub is an opportunity marketplace platform connecting opportunity seekers with opportunity providers across funding, startup programs, tenders, and jobs within a social ecosystem designed for the East African market.

The platform consists of mobile applications (iOS and Android), a web management dashboard, and a microservices backend architecture.

Core Value Proposition: Post → Apply model where organizations post opportunities and individuals/businesses apply for them.

2. AUTHENTICATION ARCHITECTURE

2.1 Overview

The authentication system supports multiple authentication methods to accommodate diverse user preferences and security requirements.

2.2 Authentication Methods

Method Description
Email + Password Traditional email-based authentication
Phone + Password Phone number with password
Username + Password Username-based login
Passwordless (Email OTP) One-time password sent via email
Passwordless (Phone OTP) One-time password sent via SMS
OAuth2 (Google) Social login via Google
OAuth2 (Apple) Social login via Apple

2.3 Token Strategy

  • Type: JWT (JSON Web Tokens)
  • Access Token: Short-lived (15-30 minutes)
  • Refresh Token: Long-lived (7-30 days)
  • Storage: Access token in memory, refresh token in secure HTTP-only cookie

2.4 Phone Verification

Phone number is required for all users and must be verified via OTP before account activation.

2.5 Account Linking

When a user signs up with one method (e.g., email) and later attempts OAuth2 with the same email, accounts will be linked automatically.

2.6 Authentication Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT (Mobile/Web)                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         API GATEWAY                              │
│                    (Rate Limiting, CORS)                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      AUTH SERVICE                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Email/     │  │  Passwordless │  │    OAuth2    │          │
│  │   Password   │  │   (OTP)       │  │  (Google/    │          │
│  │   Handler    │  │   Handler     │  │   Apple)     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │    Phone     │  │   Username   │  │    Token     │          │
│  │   Password   │  │   Password   │  │   Manager    │          │
│  │   Handler    │  │   Handler    │  │   (JWT)      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
        ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
        │  PostgreSQL │ │    Redis    │ │  External   │
        │  (Users)    │ │  (Sessions/ │ │  Providers  │
        │             │ │   OTP)      │ │  (SMS/Email)│
        └─────────────┘ └─────────────┘ └─────────────┘

2.7 OTP Flow

User Request → Generate OTP → Store in Redis (5 min TTL) → Send via SMS/Email
                                                                    │
User Submit OTP → Validate against Redis → Success → Issue JWT Tokens
                                         → Failure → Increment attempt counter

2.8 OAuth2 Flow

User clicks "Sign in with Google/Apple"
        │
        ▼
Redirect to Provider Authorization URL
        │
        ▼
User Authenticates with Provider
        │
        ▼
Provider redirects back with Authorization Code
        │
        ▼
Backend exchanges Code for Access Token
        │
        ▼
Fetch user profile from Provider
        │
        ▼
Create/Link user account → Issue JWT Tokens

3. MICROSERVICES ARCHITECTURE

3.1 High-Level System Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                                  CLIENTS                                         │
│    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐                    │
│    │   iOS App   │      │ Android App │      │   Web App   │                    │
│    │   (Swift)   │      │  (Kotlin)   │      │   (React)   │                    │
│    └─────────────┘      └─────────────┘      └─────────────┘                    │
└─────────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              API GATEWAY                                         │
│                    (Routing, Rate Limiting, Auth Validation)                     │
└─────────────────────────────────────────────────────────────────────────────────┘
                                      │
        ┌──────────┬──────────┬───────┴───────┬──────────┬──────────┐
        ▼          ▼          ▼               ▼          ▼          ▼
┌─────────────┐┌─────────────┐┌─────────────┐┌─────────────┐┌─────────────┐
│    AUTH     ││    USER     ││   SOCIAL    ││ OPPORTUNITY ││    FORM     │
│   SERVICE   ││   SERVICE   ││   SERVICE   ││   SERVICE   ││  BUILDER    │
└─────────────┘└─────────────┘└─────────────┘└─────────────┘└─────────────┘
        │              │              │              │              │
        ▼              ▼              ▼              ▼              ▼
┌─────────────┐┌─────────────┐┌─────────────┐┌─────────────┐┌─────────────┐
│APPLICATION  ││    FILE     ││NOTIFICATION ││  DIRECTORY  ││  ANALYTICS  │
│   SERVICE   ││   SERVICE   ││   SERVICE   ││   SERVICE   ││   SERVICE   │
└─────────────┘└─────────────┘└─────────────┘└─────────────┘└─────────────┘
        │              │              │              │              │
        └──────────────┴──────────────┴───────┬──────┴──────────────┘
                                              ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              DATA LAYER                                          │
│    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐                    │
│    │  PostgreSQL │      │    Redis    │      │    MinIO    │                    │
│    │  (Database) │      │   (Cache)   │      │   (Files)   │                    │
│    └─────────────┘      └─────────────┘      └─────────────┘                    │
└─────────────────────────────────────────────────────────────────────────────────┘

3.2 Services Breakdown

AUTH SERVICE

  • User registration and login
  • Multi-method authentication (email, phone, username, passwordless, OAuth2)
  • JWT token generation and validation
  • OTP generation and verification
  • Password reset flow
  • Account linking

USER SERVICE

  • User profile management
  • Role management (User, Staff, Admin)
  • Account settings
  • Privacy settings

SOCIAL SERVICE

  • Post creation (text, images, videos, links)
  • Likes, comments, shares
  • Feed generation
  • Content moderation

OPPORTUNITY SERVICE

  • Funds management (create, list, search)
  • Calls management (startup calls, proposals)
  • Business/Tenders management
  • Jobs management
  • Events management
  • Innovation showcase

FORM BUILDER SERVICE

  • Dynamic form creation (like Google Forms)
  • Field types: text, textarea, dropdown, checkbox, radio, file upload, date, etc.
  • Validation rules
  • Form templates

APPLICATION SERVICE

  • Application submission
  • Custom status management (defined by opportunity owner)
  • Application data storage
  • Export functionality (CSV/Excel)

FILE SERVICE

  • File upload/download
  • Image processing and optimization
  • MinIO integration
  • CDN management

NOTIFICATION SERVICE

  • Push notifications
  • Email notifications (via Glue Email)
  • SMS notifications (via Textfy)
  • In-app notifications

DIRECTORY SERVICE

  • People directory
  • Business directory
  • Search and filtering
  • Profile verification

ANALYTICS SERVICE

  • View counts
  • Application statistics
  • Basic analytics for opportunity owners

4. DATABASE ARCHITECTURE

4.1 Database Strategy

For MVP, all microservices share a single PostgreSQL database with schema separation per service.

┌─────────────────────────────────────────────────────────────────┐
│                      PostgreSQL Database                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ auth_schema │  │ user_schema │  │social_schema│             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ opp_schema  │  │ form_schema │  │ app_schema  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ file_schema │  │notif_schema │  │ dir_schema  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘

4.2 Core Entity Relationships

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│    USER     │───────│   PROFILE   │───────│    ROLE     │
└─────────────┘       └─────────────┘       └─────────────┘
      │                                            │
      │ creates                                    │
      ▼                                            ▼
┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│ OPPORTUNITY │───────│DYNAMIC_FORM │       │ PERMISSION  │
│ (Fund/Call/ │       │             │       │             │
│ Tender/Job/ │       └─────────────┘       └─────────────┘
│ Event)      │              │
└─────────────┘              │
      │                      ▼
      │ receives      ┌─────────────┐
      ▼               │    FORM     │
┌─────────────┐       │   FIELD     │
│ APPLICATION │───────│             │
│             │       └─────────────┘
└─────────────┘              │
      │                      ▼
      │               ┌─────────────┐
      └──────────────▶│  RESPONSE   │
                      │   DATA      │
                      └─────────────┘

4.3 Key Tables

Auth Schema

  • users - Core user credentials
  • auth_providers - OAuth2 linked accounts
  • refresh_tokens - Active refresh tokens
  • otp_requests - OTP verification tracking

User Schema

  • profiles - User profile information
  • roles - System roles (User, Staff, Admin)
  • permissions - Role permissions

Social Schema

  • posts - Social media posts
  • comments - Post comments
  • likes - Post/comment likes
  • shares - Post shares

Opportunity Schema

  • opportunities - Base opportunity table (polymorphic)
  • funds - Funding opportunities
  • calls - Startup/proposal calls
  • tenders - Business tenders
  • jobs - Job listings
  • events - Event listings
  • innovations - Innovation showcase
  • opportunity_statuses - Custom statuses per opportunity

Form Schema

  • forms - Form definitions
  • form_fields - Field definitions
  • field_options - Dropdown/radio options
  • field_validations - Validation rules

Application Schema

  • applications - Submitted applications
  • application_responses - Form field responses
  • application_files - Uploaded files
  • application_status_history - Status change log

Directory Schema

  • businesses - Business listings
  • business_categories - Business categorization

5. INFRASTRUCTURE ARCHITECTURE

5.1 Technology Stack

Layer Technology
Backend Spring Boot (Java)
Database PostgreSQL
Cache Redis
File Storage MinIO
Email Glue Email
SMS Textfy
Web Frontend React
iOS Swift
Android Kotlin

5.2 Deployment Architecture (MVP)

┌─────────────────────────────────────────────────────────────────┐
│                         LOAD BALANCER                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      APPLICATION SERVER                          │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    SPRING BOOT SERVICES                     ││
│  │  (All microservices deployed as single application for MVP) ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│  PostgreSQL │         │    Redis    │         │    MinIO    │
│             │         │             │         │             │
└─────────────┘         └─────────────┘         └─────────────┘

5.3 External Service Integration

┌─────────────────────────────────────────────────────────────────┐
│                      FURSA HUB BACKEND                           │
└─────────────────────────────────────────────────────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│ GLUE EMAIL  │         │   TEXTFY    │         │   OAUTH2    │
│  (Email)    │         │   (SMS)     │         │  PROVIDERS  │
│             │         │             │         │(Google/Apple)│
└─────────────┘         └─────────────┘         └─────────────┘

6. API DESIGN

6.1 API Standards

  • Protocol: REST over HTTPS
  • Format: JSON
  • Versioning: URL-based (e.g., /api/v1/)
  • Authentication: Bearer token (JWT)

6.2 API Structure

/api/v1
├── /auth
│   ├── POST   /register              # Register new user
│   ├── POST   /login                 # Email/phone/username login
│   ├── POST   /login/otp/request     # Request OTP
│   ├── POST   /login/otp/verify      # Verify OTP
│   ├── POST   /oauth/google          # Google OAuth2
│   ├── POST   /oauth/apple           # Apple OAuth2
│   ├── POST   /token/refresh         # Refresh access token
│   ├── POST   /logout                # Logout
│   └── POST   /password/reset        # Password reset
│
├── /users
│   ├── GET    /me                    # Current user profile
│   ├── PUT    /me                    # Update profile
│   └── GET    /:id                   # Get user by ID
│
├── /social
│   ├── GET    /feed                  # Get feed
│   ├── POST   /posts                 # Create post
│   ├── GET    /posts/:id             # Get post
│   ├── PUT    /posts/:id             # Update post
│   ├── DELETE /posts/:id             # Delete post
│   ├── POST   /posts/:id/like        # Like post
│   ├── DELETE /posts/:id/like        # Unlike post
│   ├── POST   /posts/:id/comments    # Add comment
│   ├── GET    /posts/:id/comments    # Get comments
│   └── POST   /posts/:id/share       # Share post
│
├── /opportunities
│   ├── GET    /funds                 # List funds
│   ├── POST   /funds                 # Create fund
│   ├── GET    /funds/:id             # Get fund details
│   ├── PUT    /funds/:id             # Update fund
│   ├── DELETE /funds/:id             # Delete fund
│   │
│   ├── GET    /calls                 # List calls
│   ├── POST   /calls                 # Create call
│   ├── GET    /calls/:id             # Get call details
│   │
│   ├── GET    /tenders               # List tenders
│   ├── POST   /tenders               # Create tender
│   ├── GET    /tenders/:id           # Get tender details
│   │
│   ├── GET    /jobs                  # List jobs
│   ├── POST   /jobs                  # Create job
│   ├── GET    /jobs/:id              # Get job details
│   │
│   ├── GET    /events                # List events
│   ├── POST   /events                # Create event
│   ├── GET    /events/:id            # Get event details
│   │
│   └── GET    /innovations           # List innovations
│
├── /forms
│   ├── POST   /                      # Create dynamic form
│   ├── GET    /:id                   # Get form structure
│   ├── PUT    /:id                   # Update form
│   └── DELETE /:id                   # Delete form
│
├── /applications
│   ├── POST   /                      # Submit application
│   ├── GET    /my                    # My applications
│   ├── GET    /opportunity/:id       # Applications for opportunity
│   ├── GET    /:id                   # Get application details
│   ├── PUT    /:id/status            # Update application status
│   └── GET    /opportunity/:id/export # Export applications (CSV)
│
├── /directory
│   ├── GET    /people                # Search people
│   ├── GET    /businesses            # Search businesses
│   └── GET    /businesses/:id        # Get business details
│
├── /files
│   ├── POST   /upload                # Upload file
│   └── GET    /:id                   # Get file
│
└── /notifications
    ├── GET    /                      # Get notifications
    ├── PUT    /:id/read              # Mark as read
    └── PUT    /read-all              # Mark all as read

6.3 Response Format

Success Response:

{
  "success": true,
  "data": { },
  "message": "Operation successful"
}

Error Response:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Paginated Response:

{
  "success": true,
  "data": [ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

7. DYNAMIC FORM SYSTEM

7.1 Overview

The form builder allows opportunity owners to create custom application forms similar to Google Forms.

7.2 Form Structure

{
  "id": "uuid",
  "opportunityId": "uuid",
  "title": "Application Form",
  "description": "Please fill out this form",
  "fields": [
    {
      "id": "uuid",
      "type": "text",
      "label": "Full Name",
      "placeholder": "Enter your full name",
      "required": true,
      "order": 1
    },
    {
      "id": "uuid",
      "type": "dropdown",
      "label": "Experience Level",
      "required": true,
      "options": ["Junior", "Mid-Level", "Senior"],
      "order": 2
    },
    {
      "id": "uuid",
      "type": "file",
      "label": "Upload CV",
      "required": true,
      "allowedTypes": ["pdf", "doc", "docx"],
      "maxSize": 5242880,
      "order": 3
    }
  ]
}

7.3 Supported Field Types

Type Description
text Single line text input
textarea Multi-line text input
number Numeric input
email Email input with validation
phone Phone number input
date Date picker
datetime Date and time picker
dropdown Single select dropdown
multiselect Multiple select
radio Radio button group
checkbox Checkbox group
file File upload
url URL input with validation

8. APPLICATION STATUS SYSTEM

8.1 Custom Status Flow

Each opportunity owner defines their own status workflow:

Owner creates opportunity
        │
        ▼
Owner defines custom statuses
Example: ["Received", "Under Review", "Shortlisted", "Interview", "Accepted", "Rejected"]
        │
        ▼
Applicants submit applications (default status: first in list)
        │
        ▼
Owner manually updates status as needed
        │
        ▼
Applicant receives notification on status change

8.2 Status Configuration

{
  "opportunityId": "uuid",
  "statuses": [
    { "id": 1, "name": "Received", "color": "#gray", "isDefault": true },
    { "id": 2, "name": "Under Review", "color": "#blue" },
    { "id": 3, "name": "Shortlisted", "color": "#yellow" },
    { "id": 4, "name": "Accepted", "color": "#green", "isFinal": true },
    { "id": 5, "name": "Rejected", "color": "#red", "isFinal": true }
  ]
}

9. USER ROLES & PERMISSIONS

9.1 System Roles

Role Description
User Regular platform user - can apply and create opportunities
Staff Fursa Hub team member - helps with platform management
Admin Full platform access - manages users, content, and settings

9.2 Permission Matrix

Action User Staff Admin
Create opportunities ✓ ✓ ✓
Apply to opportunities ✓ ✓ ✓
Manage own content ✓ ✓ ✓
View all applications ✗ ✓ ✓
Moderate content ✗ ✓ ✓
Manage users ✗ ✗ ✓
System settings ✗ ✗ ✓

10. NOTIFICATION SYSTEM

10.1 Notification Channels

Channel Provider Use Case
Push FCM/APNs Real-time mobile alerts
Email Glue Email Formal communications
SMS Textfy OTP, critical alerts
In-App Internal Activity feed

10.2 Notification Events

Event Push Email SMS In-App
New application received ✓ ✓ ✗ ✓
Application status changed ✓ ✓ ✗ ✓
Application submitted (confirmation) ✗ ✓ ✗ ✓
New comment on post ✓ ✗ ✗ ✓
New like on post ✗ ✗ ✗ ✓
OTP verification ✗ ✓ ✓ ✗
Password reset ✗ ✓ ✗ ✗

11. SECURITY CONSIDERATIONS

11.1 Authentication Security

  • Password hashing using BCrypt (strength 12)
  • JWT tokens with short expiry
  • Refresh token rotation
  • Rate limiting on auth endpoints
  • Account lockout after failed attempts
  • OTP expiry (5 minutes)
  • OTP attempt limits

11.2 API Security

  • HTTPS only
  • CORS configuration
  • Request validation
  • SQL injection prevention (parameterized queries)
  • XSS prevention
  • Rate limiting per user/IP

11.3 Data Security

  • Encryption at rest (database)
  • Encryption in transit (TLS)
  • File upload validation
  • Sensitive data masking in logs

12. SCALABILITY PATH

12.1 MVP Phase (Current)

  • Monolithic deployment (all services in one application)
  • Single PostgreSQL database
  • Single Redis instance
  • Single MinIO instance

12.2 Growth Phase (Future)

  • Split into separate microservices
  • Database per service
  • Redis cluster
  • MinIO cluster or cloud storage (S3)
  • Message queue (RabbitMQ/Kafka)
  • Kubernetes orchestration

14. APPENDIX

14.1 Glossary

Term Definition
Opportunity Any postable item (Fund, Call, Tender, Job, Event, Innovation)
Owner User who creates an opportunity
Applicant User who applies to an opportunity
Dynamic Form Custom form created by opportunity owner

14.2 Contact

For technical questions regarding this architecture, please contact the development team.

No comments to display

Back to top