Initial commit: SIBU 2.0 MISSION

old/README-POSTGRESQL-SETUP.md

@@ -0,0 +1,210 @@
+# PostgreSQL Direct Connection Setup
+
+This guide explains how to use the PostgreSQL database directly instead of Supabase.
+
+## Architecture
+
+Since Flutter web cannot connect directly to PostgreSQL from the browser (security restrictions), we use a two-tier architecture:
+
+```
+Flutter App (Web) → FastAPI Backend → PostgreSQL Database
+```
+
+The backend acts as an API layer that connects to PostgreSQL and exposes REST endpoints.
+
+## Database Configuration
+
+The PostgreSQL database is configured as:
+- **Host**: localhost
+- **Port**: 5432
+- **Database**: sibu
+- **Username**: sibu
+- **Password**: sibu
+
+Connection string: `postgresql+asyncpg://sibu:sibu@localhost:5432/sibu`
+
+## Setup Steps
+
+### 1. Ensure PostgreSQL is Running
+
+Make sure your PostgreSQL database is running and accessible:
+
+```bash
+# Test connection (if you have psql installed)
+psql -h localhost -p 5432 -U sibu -d sibu
+```
+
+### 2. Apply Database Migrations
+
+The database schema needs to be created. You have two options:
+
+#### Option A: Use Supabase Migrations
+
+If you have the Supabase migrations in `supabase/migrations/`, you can apply them directly:
+
+```bash
+# Connect to PostgreSQL and run migrations
+psql -h localhost -p 5432 -U sibu -d sibu -f supabase/migrations/20241019215951_sibu_transportation_system.sql
+# ... apply other migrations
+```
+
+#### Option B: Use Alembic (Backend Migrations)
+
+The backend uses Alembic for migrations:
+
+```bash
+cd backend
+uv run alembic upgrade head
+```
+
+### 3. Start the Backend API
+
+```bash
+cd backend
+uv run fastapi dev app/main.py
+```
+
+The API will be available at `http://localhost:8000`
+
+### 4. Run Flutter App
+
+```bash
+cd old
+./scripts/run-flutter-backend.sh
+```
+
+Or manually:
+
+```bash
+flutter run -d chrome --dart-define=API_BASE_URL=http://localhost:8000
+```
+
+## Backend API Endpoints
+
+The backend provides the following endpoints:
+
+- `GET /api/routes` - Get all routes
+- `GET /api/routes/{route_id}` - Get specific route
+- `GET /api/bus-stops` - Get all bus stops
+- `GET /api/bus-stops/{stop_id}` - Get specific bus stop
+- `GET /api/schedules` - Get schedules (with optional route_id, stop_id filters)
+- `GET /api/coupons` - Get coupons (with optional category, is_active filters)
+- `GET /api/taxis` - Get taxis (with optional filters)
+- `GET /health` - Health check
+
+## Configuration Files
+
+### Backend Configuration
+
+**File**: `backend/.env.development`
+```env
+DATABASE_URL=postgresql+asyncpg://sibu:sibu@localhost:5432/sibu
+ENVIRONMENT=development
+DEBUG=true
+```
+
+**File**: `backend/app/core/config.py`
+- Default database URL is set to your PostgreSQL connection
+
+### Flutter Configuration
+
+The Flutter app uses `ApiClient` service which:
+- Defaults to `http://localhost:8000`
+- Can be configured via `--dart-define=API_BASE_URL=<url>`
+
+## Switching Between Supabase and PostgreSQL
+
+### Use PostgreSQL (via Backend API)
+```bash
+cd old
+./scripts/run-flutter-backend.sh
+```
+
+### Use Supabase
+```bash
+cd old
+./scripts/run-flutter-local.sh  # For local Supabase
+# OR
+flutter run -d chrome \
+  --dart-define=SUPABASE_URL=<url> \
+  --dart-define=SUPABASE_ANON_KEY=<key>
+```
+
+## Troubleshooting
+
+### Backend Can't Connect to PostgreSQL
+
+1. **Check PostgreSQL is running:**
+   ```bash
+   # macOS
+   brew services list | grep postgresql
+   
+   # Or check if port is listening
+   lsof -i :5432
+   ```
+
+2. **Verify credentials:**
+   ```bash
+   psql -h localhost -p 5432 -U sibu -d sibu
+   ```
+
+3. **Check database exists:**
+   ```sql
+   \l  -- List databases
+   ```
+
+### Flutter Can't Connect to Backend
+
+1. **Check backend is running:**
+   ```bash
+   curl http://localhost:8000/health
+   ```
+
+2. **Check CORS settings** in `backend/app/main.py`
+
+3. **Verify API URL** in Flutter:
+   ```dart
+   // Check ApiClient base URL
+   print(ApiClient.instance._baseUrl);
+   ```
+
+### Database Schema Issues
+
+If tables don't exist:
+
+1. **Apply migrations:**
+   ```bash
+   cd backend
+   uv run alembic upgrade head
+   ```
+
+2. **Or manually create from Supabase migrations:**
+   ```bash
+   psql -h localhost -p 5432 -U sibu -d sibu < supabase/migrations/20241019215951_sibu_transportation_system.sql
+   ```
+
+## Development Workflow
+
+1. **Start PostgreSQL** (if not running as a service)
+2. **Start Backend API:**
+   ```bash
+   cd backend
+   uv run fastapi dev app/main.py
+   ```
+3. **Run Flutter App:**
+   ```bash
+   cd old
+   ./scripts/run-flutter-backend.sh
+   ```
+
+## Next Steps
+
+The Flutter app services need to be updated to use `ApiClient` instead of `SupabaseService`. Currently, the app still uses Supabase. To fully migrate:
+
+1. Update `TransportationService` to use `ApiClient`
+2. Update `CouponService` to use `ApiClient`
+3. Update `TaxiService` to use `ApiClient`
+4. Remove or make optional `SupabaseService`
+
+This migration can be done incrementally.
+