🏦 BOC Life Retirement Package Booking Platform

A comprehensive booking platform for BOC Life policy holders to redeem retirement packages using their accumulated points.

📊 System Architecture

High-Level Architecture

graph TB
    subgraph "Client Layer"
        A[Flutter Web App]
        B[Flutter iOS App]
        C[Flutter Android App]
        D[Admin Dashboard]
    end

    subgraph "Application Layer"
        E[FastAPI Backend<br/>Python 3.12+]
        F[Directus CMS<br/>Node.js]
    end

    subgraph "Data Layer"
        G[(PostgreSQL 15<br/>Main Database)]
        H[(Redis Cache)]
    end

    subgraph "AWS Cloud Services"
        I[S3 Bucket<br/>File Storage]
        J[SNS<br/>SMS/OTP]
        K[SES<br/>Email Service]
        L[CloudFront<br/>CDN]
        M[EC2/ECS<br/>Hosting]
    end

    A --> E
    B --> E
    C --> E
    D --> F
    E --> F
    E --> G
    E --> H
    F --> G
    E --> I
    E --> J
    E --> K
    A --> L
    B --> L
    C --> L
    E --> M
    F --> M

    style E fill:#e3f2fd
    style F fill:#fff3e0
    style G fill:#f3e5f5
    style H fill:#fce4ec

API Architecture & Data Flow

sequenceDiagram
    participant User as User/Client
    participant API as FastAPI Backend
    participant Cache as Redis Cache
    participant DB as PostgreSQL
    participant CMS as Directus CMS
    participant AWS as AWS Services

    User->>API: Request Package List
    API->>Cache: Check Cache
    alt Cache Hit
        Cache-->>API: Return Cached Data
    else Cache Miss
        API->>CMS: Fetch Packages
        CMS->>DB: Query Data
        DB-->>CMS: Package Data
        CMS-->>API: Package List
        API->>Cache: Store in Cache
    end
    API-->>User: Return Packages

    User->>API: Create Booking
    API->>DB: Validate Points
    DB-->>API: Points Available
    API->>DB: Create Booking & Deduct Points
    API->>AWS: Send Confirmation Email (SES)
    API->>CMS: Log Booking Event
    API-->>User: Booking Confirmation

Authentication Flow

sequenceDiagram
    participant User as User
    participant App as Flutter App
    participant API as FastAPI
    participant SNS as AWS SNS
    participant DB as Database

    User->>App: Enter Invitation Code
    App->>API: POST /auth/verify-invitation
    API->>DB: Validate Invitation Code
    DB-->>API: Code Valid
    API-->>App: Code Verified

    User->>App: Enter Phone Number
    App->>API: POST /auth/request-otp
    API->>SNS: Send OTP SMS
    SNS-->>User: OTP SMS
    API-->>App: OTP Sent

    User->>App: Enter OTP
    App->>API: POST /auth/verify-otp
    API->>DB: Verify OTP
    DB-->>API: OTP Valid
    API->>DB: Create/Update User
    API-->>App: JWT Access Token
    App-->>User: Authenticated

Booking System Flow

flowchart TD
    A[User Browses Packages] --> B{Filter by Location?}
    B -->|Yes| C[Select City/Region]
    B -->|No| D[View All Packages]
    C --> E[Display Filtered Packages]
    D --> E

    E --> F[Select Package]
    F --> G[Check Availability]
    G --> H{Available?}
    H -->|No| I[Show Alternative Dates]
    H -->|Yes| J[Check Points Balance]

    J --> K{Sufficient Points?}
    K -->|No| L[Show Insufficient Points]
    K -->|Yes| M[Enter Guest Details]

    M --> N[Review Booking]
    N --> O{Confirm?}
    O -->|No| P[Cancel/Edit]
    O -->|Yes| Q[Process Booking]

    Q --> R[Deduct Points]
    R --> S[Create Booking Record]
    S --> T[Send Email Confirmation]
    T --> U[Update Availability]
    U --> V[Booking Complete]

    I --> F
    L --> E
    P --> M

    style Q fill:#4caf50,color:#fff
    style V fill:#2196f3,color:#fff
    style L fill:#f44336,color:#fff

Database Schema Overview

erDiagram
    USERS ||--o{ BOOKINGS : creates
    USERS ||--o{ POINTS_TRANSACTIONS : has
    CAMPAIGNS ||--o{ INVITATION_CODES : generates
    INVITATION_CODES ||--o| USERS : used_by
    PACKAGES ||--o{ BOOKINGS : booked_in
    HOTELS ||--o{ PACKAGES : contains
    CITIES ||--o{ HOTELS : located_in

    USERS {
        string id PK
        string phone_number UK
        string email
        string full_name
        string language
        int total_points
        datetime created_at
        datetime last_login
    }

    CAMPAIGNS {
        string id PK
        string name
        string description
        int points_allocation
        datetime start_date
        datetime end_date
        boolean is_active
    }

    INVITATION_CODES {
        string code PK
        string campaign_id FK
        string user_id FK
        boolean is_used
        datetime used_at
        datetime expires_at
    }

    PACKAGES {
        string id PK
        string hotel_id FK
        string name_en
        string name_zh_hk
        string name_zh_cn
        int points_required
        int max_guests
        boolean is_active
    }

    HOTELS {
        string id PK
        string city_id FK
        string name
        string address
        float rating
        string image_url
    }

    BOOKINGS {
        string id PK
        string booking_code UK
        string user_id FK
        string package_id FK
        date check_in_date
        date check_out_date
        int points_used
        string status
        datetime created_at
    }

    POINTS_TRANSACTIONS {
        string id PK
        string user_id FK
        int points_change
        string transaction_type
        string reference_id
        datetime created_at
    }

🚀 Tech Stack

Backend

Framework: FastAPI (Python 3.12+)
Database: PostgreSQL 15+
Cache: Redis 7
ORM/Query: py-directus, httpx
Authentication: JWT (python-jose)
Password Hashing: bcrypt (passlib)

CMS

Platform: Directus (Latest)
SDK: @directus/sdk v20.0.1
Runtime: Node.js 18+ / Bun

Frontend

Framework: Flutter 3.16+
Platforms: Web, iOS, Android
Languages: Dart

Infrastructure

Cloud Provider: AWS
Compute: EC2/ECS
Database: RDS PostgreSQL
Storage: S3
CDN: CloudFront
Messaging: SNS (SMS/OTP)
Email: SES
Container: Docker
Orchestration: Docker Compose

Development Tools

Package Manager: Bun, pip, uv
Type Checking: TypeScript 5.0+, Pydantic
API Documentation: Swagger UI, ReDoc

✨ Key Features

🔐 User Authentication

✅ Invitation code validation for policy holders
✅ AWS SNS OTP verification via SMS
✅ Multi-language support (English, Traditional Chinese, Simplified Chinese)
✅ Secure JWT token-based authentication
✅ Session management with Redis

📦 Package Management

✅ Location-based package filtering (by city/region)
✅ Real-time availability checking
✅ Points-based redemption system
✅ Multi-language content support
✅ Package search and advanced filtering
✅ Hotel ratings and reviews

🎫 Booking System

✅ Complete booking flow with guest details
✅ Points validation and automatic deduction
✅ Email confirmations via AWS SES
✅ Booking modification and cancellation
✅ Booking history and status tracking
✅ Unique booking code generation

⚙️ Admin Features (Directus CMS)

✅ Campaign code generation and management
✅ Hotel and package administration
✅ User management and analytics
✅ Content management in multiple languages
✅ News and announcements
✅ UI translation management

📊 Points System

✅ Points balance tracking
✅ Points transaction history
✅ Points allocation via campaigns
✅ Automatic points deduction on booking
✅ Points refund on cancellation

📱 Platform Coverage

Platform	Technology	Status
📱 Mobile Web	Flutter Web	✅ Supported
🍎 iOS	Flutter Native	✅ Supported
🤖 Android	Flutter Native	✅ Supported
💼 Admin Panel	Directus CMS	✅ Supported

🔧 Quick Start

Prerequisites

Ensure you have the following installed:

Python: 3.12 or higher
Node.js: 18 or higher (or Bun)
Flutter: 3.16 or higher
PostgreSQL: 15 or higher
Redis: 7 or higher
Docker: Latest version (for containerized setup)
AWS Account: With SNS/SES access configured

Option 1: Docker Compose (Recommended)

This is the fastest way to get the entire platform running locally.

# 1. Clone the repository
git clone <repository-url>
cd fast_boc_life_retirement_package_booking_platform

# 2. Copy environment configuration
cp .env.example .env
# Edit .env with your configuration

# 3. Start all services
docker-compose up -d

# 4. Wait for services to start (check logs)
docker-compose logs -f

# 5. Access the services
# - Backend API: http://localhost:8000
# - API Docs: http://localhost:8000/docs
# - Directus CMS: http://localhost:8055
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379

Option 2: Manual Setup

Backend Setup (FastAPI)

# 1. Navigate to backend directory
cd backend

# 2. Create virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env with your database and AWS credentials

# 5. Run database migrations (if using Alembic)
alembic upgrade head

# 6. Start the development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Server will be available at http://localhost:8000

Python UV Setup (Alternative)

# Using UV package manager for faster dependency resolution
uv pip install -r requirements.txt
uv run uvicorn main:app --reload

Directus CMS Setup

# 1. Navigate to CMS directory
cd _directus

# 2. Install dependencies
npm install
# Or using Bun (faster)
bun install

# 3. Configure environment
cp .env.example .env
# Edit .env with database credentials

# 4. Bootstrap Directus
npx directus bootstrap

# 5. Start Directus
npx directus start
# Or with Bun
bun run directus start

# Directus will be available at http://localhost:8055

Frontend Setup (Flutter)

# 1. Navigate to Flutter app directory
cd flutter_app

# 2. Install dependencies
flutter pub get

# 3. Configure environment
cp lib/core/config/config.example.dart lib/core/config/config.dart
# Edit config.dart with your API endpoints

# 4. Run on different platforms

# Web
flutter run -d chrome

# iOS (requires macOS and Xcode)
flutter run -d ios

# Android
flutter run -d android

# Build for production
flutter build web --release
flutter build ios --release
flutter build apk --release

Database Setup

# Using Docker for PostgreSQL
docker run -d \
  --name boclife-postgres \
  -e POSTGRES_USER=boclife \
  -e POSTGRES_PASSWORD=boclife123 \
  -e POSTGRES_DB=boc_retirement \
  -p 5432:5432 \
  postgres:15-alpine

# Using Docker for Redis
docker run -d \
  --name boclife-redis \
  -p 6379:6379 \
  redis:7-alpine

🔐 Environment Variables

Backend (.env)

# Application
APP_NAME=BOC Life Retirement Package API
API_V1_STR=/api/v1
DEBUG=True

# Database
DATABASE_URL=postgresql://boclife:boclife123@localhost:5432/boc_retirement

# JWT Authentication
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Redis
REDIS_URL=redis://localhost:6379

# AWS Configuration
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_REGION=ap-east-1
AWS_S3_BUCKET=boclife-retirement-uploads

# AWS SNS (for OTP)
AWS_SNS_SENDER_ID=BOCLife

# AWS SES (for Email)
[email protected]

# Directus
DIRECTUS_URL=http://localhost:8055
DIRECTUS_TOKEN=your-directus-static-token

# CORS
CORS_ORIGINS=["http://localhost:3000","http://localhost:8080"]

Directus CMS (.env)

# Server
PORT=8055
PUBLIC_URL=http://localhost:8055

# Database
DB_CLIENT=pg
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=directus
DB_USER=boclife
DB_PASSWORD=boclife123

# Security
KEY=your-directus-key-min-32-characters
SECRET=your-directus-secret-min-32-characters

# Admin Account
[email protected]
ADMIN_PASSWORD=change-this-secure-password

# Storage
STORAGE_LOCATIONS=local
STORAGE_LOCAL_DRIVER=local
STORAGE_LOCAL_ROOT=./uploads

# Email (Optional)
[email protected]
EMAIL_TRANSPORT=smtp
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
[email protected]
EMAIL_SMTP_PASSWORD=your-app-password

# Extensions
EXTENSIONS_PATH=./extensions

📁 Project Structure

fast_boc_life_retirement_package_booking_platform/
│
├── backend/                    # FastAPI Backend Application
│   ├── api/                    # API Routes
│   │   ├── v1/                 # API Version 1
│   │   │   ├── auth/           # Authentication endpoints
│   │   │   ├── users/          # User management
│   │   │   ├── packages/       # Package endpoints
│   │   │   ├── hotels/         # Hotel endpoints
│   │   │   └── bookings/       # Booking endpoints
│   │   ├── admin/              # Admin endpoints
│   │   └── dependencies.py     # Shared dependencies
│   ├── config/                 # Configuration
│   │   └── settings.py         # App settings
│   ├── schemas/                # Pydantic schemas
│   ├── services/               # Business logic services
│   ├── main.py                 # Application entry point
│   ├── requirements.txt        # Python dependencies
│   └── Dockerfile              # Docker configuration
│
├── _directus/                  # Directus CMS Integration
│   ├── index.ts                # Directus SDK client
│   ├── directus-setup.js       # Setup scripts
│   ├── package.json            # Node dependencies
│   └── README.md               # Directus documentation
│
├── cms/                        # CMS Data & Schema
│   ├── directus_schema.json    # Complete schema export
│   ├── directus_collections.json # Collections configuration
│   ├── directus_complete_schema.json # Full schema backup
│   └── uploads/                # User uploads (gitignored)
│
├── deployment/                 # Deployment Configuration
│   └── init-db.sh              # Database initialization script
│
├── scripts/                    # Utility Scripts
│   └── ...                     # Various helper scripts
│
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile                  # Main application Dockerfile
├── package.json                # Root Node.js configuration
├── pyproject.toml              # Python project configuration (UV)
├── tsconfig.json               # TypeScript configuration
├── .env.example                # Environment variables template
└── README.md                   # This file

🌐 API Documentation

Once the backend is running, interactive API documentation is available at:

Swagger UI: http://localhost:8000/docs
Interactive API testing interface
Try out endpoints directly
View request/response schemas
ReDoc: http://localhost:8000/redoc
Clean, readable API documentation
Better for documentation reference

🔑 Key API Endpoints

Authentication

Method	Endpoint	Description
POST	`/api/v1/auth/verify-invitation`	Verify invitation code
POST	`/api/v1/auth/request-otp`	Request OTP SMS
POST	`/api/v1/auth/verify-otp`	Verify OTP and get JWT token
POST	`/api/v1/auth/register`	Register new user
POST	`/api/v1/auth/login`	User login

Packages & Hotels

Method	Endpoint	Description
GET	`/api/v1/packages`	List all available packages
GET	`/api/v1/packages/{id}`	Get package details
GET	`/api/v1/packages/search`	Advanced package search
GET	`/api/v1/hotels`	List all hotels
GET	`/api/v1/hotels/cities`	Get available cities
GET	`/api/v1/hotels/news`	Get latest news updates

Bookings

Method	Endpoint	Description
POST	`/api/v1/bookings`	Create new booking
GET	`/api/v1/bookings`	Get user's bookings
GET	`/api/v1/bookings/{code}`	Get booking details
PUT	`/api/v1/bookings/{code}`	Update booking
POST	`/api/v1/bookings/{code}/cancel`	Cancel booking

User Profile

Method	Endpoint	Description
GET	`/api/v1/users/me`	Get current user profile
PUT	`/api/v1/users/me`	Update user profile
GET	`/api/v1/users/dashboard`	Get user dashboard data

Admin

Method	Endpoint	Description
POST	`/api/v1/admin/campaigns`	Create campaign
GET	`/api/v1/admin/campaigns`	List all campaigns
POST	`/api/v1/admin/campaigns/{id}/generate-invitations`	Generate invitation codes
GET	`/api/v1/admin/statistics`	Get admin statistics

🚀 Deployment

Docker Deployment

# Build all images
docker-compose build

# Start services in production mode
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# View logs
docker-compose logs -f backend

# Stop services
docker-compose down

AWS Deployment

Backend (ECS/EC2)

# 1. Build Docker image
docker build -t boclife-api:latest ./backend

# 2. Tag for ECR
docker tag boclife-api:latest <aws-account-id>.dkr.ecr.ap-east-1.amazonaws.com/boclife-api:latest

# 3. Login to ECR
aws ecr get-login-password --region ap-east-1 | \
  docker login --username AWS --password-stdin <aws-account-id>.dkr.ecr.ap-east-1.amazonaws.com

# 4. Push to ECR
docker push <aws-account-id>.dkr.ecr.ap-east-1.amazonaws.com/boclife-api:latest

# 5. Update ECS service
aws ecs update-service --cluster boclife-cluster --service boclife-api --force-new-deployment

Flutter Web (S3 + CloudFront)

# 1. Build Flutter web app
cd flutter_app
flutter build web --release

# 2. Sync to S3
aws s3 sync build/web/ s3://boclife-web-app/ --delete

# 3. Invalidate CloudFront cache
aws cloudfront create-invalidation \
  --distribution-id <DISTRIBUTION_ID> \
  --paths "/*"

🧪 Testing

Backend Testing

# Run all tests
cd backend
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_auth.py

# Run with verbose output
pytest -v

Frontend Testing

cd flutter_app

# Unit tests
flutter test

# Integration tests
flutter test integration_test/

# Widget tests
flutter test test/widgets/

# Generate coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

🌍 Internationalization (i18n)

The platform supports three languages:

Language	Code	Coverage
English	`en`	✅ Full
Traditional Chinese	`zh-HK`	✅ Full
Simplified Chinese	`zh-CN`	✅ Full

Managing Translations

Backend (FastAPI)

Translations are stored in Directus CMS and accessed via API.

Frontend (Flutter)

# Generate translations
flutter gen-l10n

# Translation files location
lib/l10n/
├── app_en.arb
├── app_zh_HK.arb
└── app_zh_CN.arb

Directus CMS

All content fields support multi-language input directly in the admin interface.

📊 Monitoring & Observability

Health Checks

# Backend health check
curl http://localhost:8000/health

# Directus health check
curl http://localhost:8055/server/health

Logs

# Docker logs
docker-compose logs -f backend
docker-compose logs -f directus

# Application logs (if running locally)
tail -f logs/app.log

Metrics

Application metrics available at /metrics endpoint
AWS CloudWatch for production monitoring
Database query performance via PostgreSQL logs

🔧 Development Guidelines

Code Style

Python: Follow PEP 8, use black formatter bash black backend/ flake8 backend/
TypeScript/JavaScript: Use Prettier bash npm run format npm run lint
Flutter/Dart: Follow official Dart style guide bash dart format . flutter analyze

Git Workflow

# Branch naming
feature/your-feature-name
bugfix/issue-description
hotfix/critical-fix

# Commit messages (Conventional Commits)
feat: add points balance endpoint
fix: resolve OTP verification timeout
docs: update API documentation
refactor: optimize booking service

Pull Request Process

Create feature branch from main or develop
Implement changes with appropriate tests
Update documentation if needed
Ensure all tests pass
Create PR with clear description
Request code review
Address review comments
Merge after approval

🛠️ Troubleshooting

Common Issues

Backend Won't Start

Symptom: Server fails to start

# Check logs
docker-compose logs backend

# Common fixes:
# 1. Check database connection
docker-compose ps postgres

# 2. Verify environment variables
cat .env

# 3. Check port availability
lsof -i :8000

OTP Not Sending

Symptom: OTP SMS not received

# Verify AWS SNS configuration
aws sns list-phone-numbers-opted-out

# Check AWS credentials
aws sts get-caller-identity

# Review IAM permissions for SNS

Database Connection Issues

# Test PostgreSQL connection
docker-compose exec postgres psql -U boclife -d boc_retirement -c "SELECT 1;"

# Reset database
docker-compose down -v
docker-compose up -d postgres

Flutter Build Fails

# Clean Flutter build
flutter clean
flutter pub get
flutter pub upgrade

# Clear Flutter cache
rm -rf ~/.pub-cache
flutter pub cache repair

Logs Location

Service	Location
Backend	`logs/app.log`
Directus	`cms/logs/directus.log`
PostgreSQL	`docker logs boclife-postgres`
Redis	`docker logs boclife-redis`

📞 Support & Contact

Technical Contact

Developer: Victor
Email: [email protected]

Documentation

Getting Help

Check this README for setup instructions
Review API documentation at /docs
Check the troubleshooting section
Contact the development team

📄 License

This project is proprietary software developed for BOC Life Insurance.

🤝 Contributing

This is a private project. For authorized contributors:

Follow the development guidelines above
Ensure all tests pass before submitting PR
Update documentation for new features
Coordinate with stakeholders for major changes
Maintain code quality and security standards

🔒 Security

Security Best Practices

✅ JWT token-based authentication
✅ Password hashing with bcrypt
✅ SQL injection prevention (parameterized queries)
✅ CORS configuration
✅ Rate limiting on authentication endpoints
✅ Secure environment variable management
✅ HTTPS in production
✅ Regular security audits

Reporting Security Issues

If you discover a security vulnerability, please email [email protected] immediately.

Do not create public issues for security vulnerabilities.

Built with ❤️ for BOC Life Insurance policy holders

Last Updated: November 2024