Roadmap | Blokid

Scope

# Implementation Plan
# Production Migration Plan: SaaS POC → Microservices Architecture

## Overview

Migrate 51 self-contained FastAPI HTML apps into a unified production architecture:
- **Shared Python library** for duplicated code (encryption, database, config) ✅ DONE
- **Shared Auth Service** for user registration, login, JWT issuance ✅ DONE
- **API Gateway** for centralized routing, auth validation, rate limiting ✅ DONE
- **REST API Microservices** (JSON-only, no HTML templates) ✅ 27 services migrated (24 *-service + 3 hybrid)
- **React Frontend** (single SPA replacing Jinja2 UIs) ✅ DONE (27 analysis detail pages)
- **Cloud SQL PostgreSQL** per service (replacing SQLite)
- **GKE (Google Kubernetes Engine)** for container orchestration
- **Helm Charts** for Kubernetes packaging ✅ 31 helm chart directories created
- **ArgoCD** for GitOps continuous deployment
- **Terraform** for GCP infrastructure as code
- **Discovery Agent** for vendor discovery ✅ DONE

### Current Migration Status (as of March 2026)

| Component | Status | Details |
|-----------|--------|---------|
| POC apps | 51 built | All have app/templates/ |
| Microservices | 27 migrated | 24 *-service dirs + 3 hybrid (slack/github/notion) |
| Helm charts | 31 created | All services + gateway + frontend + discovery-agent |
| Frontend pages | 27 analysis pages | Plus auth, dashboard, discovery, callback pages |
| POC-only (not yet migrated) | 28 remaining | adobe, adp, anrok, anthropic, appsignal, auth0, crowdstrike, databricks, dhl, easypost, fedex, figma, googlebigquery, kandji, klaviyo, linkedin, openai, shippo, shipstation, snowflake, ups, usps, verizon, workday, zoho_inventory |

---

## Phase 1: Shared Python Library (`blokid_common`)

**Goal:** Extract duplicated code from 36 apps into a shared installable package.

**Create:** `/saas-poc/shared/blokid_common/`

```
shared/
├── pyproject.toml
├── blokid_common/
│   ├── __init__.py
│   ├── config.py          # Base Settings class (pydantic-settings)
│   ├── database.py         # Engine factory, get_db(), Base
│   ├── encryption.py       # Unified encrypt/decrypt (supports both patterns)
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── jwt.py          # JWT creation/validation helpers
│   │   └── dependencies.py # FastAPI deps: get_current_user, require_auth
│   ├── models/
│   │   ├── __init__.py
│   │   └── base.py         # RiskLevel enum, base Finding/Analysis schemas
│   ├── middleware/
│   │   ├── __init__.py
│   │   └── gateway.py      # Middleware to read X-User-ID from gateway headers
│   ├── migrations/
│   │   ├── __init__.py
│   │   └── utils.py        # Alembic helper functions (init_alembic, run_migrations)
│   └── schemas/
│       ├── __init__.py
│       └── api.py          # Standardized API response schemas (ErrorResponse, PaginatedResponse, etc.)
```

**Key decisions:**
- Installable via `pip install -e ../shared` in each service
- `BaseServiceConfig(BaseSettings)` with common fields: `DATABASE_URL`, `ENCRYPTION_KEY`, `JWT_SECRET`, `SERVICE_NAME`, `DEBUG`
- `create_engine_from_url(url)` factory that handles SQLite vs PostgreSQL
- Unified `encrypt_token()` / `decrypt_token()` supporting both Fernet direct-key and PBKDF2-derived patterns (for backward compat with existing encrypted data)

**Shared dependencies (in pyproject.toml):**
```toml
[project]
dependencies = [
    "fastapi>=0.109.0",
    "sqlalchemy>=2.0.25",
    "alembic>=1.13.0",
    "pydantic>=2.5.3",
    "pydantic-settings>=2.1.0",
    "cryptography>=42.0.0",
    "python-jose[cryptography]>=3.3.0",
    "passlib[bcrypt]>=1.7.4",
    "psycopg2-binary>=2.9.9",
]
```

---

## Phase 2: Auth Service

**Goal:** Centralized user management and JWT issuance. All other services trust JWTs from this service.

**Create:** `/saas-poc/auth-service/`

```
auth-service/
├── main.py
├── requirements.txt
├── alembic.ini                 # Alembic configuration
├── migrations/
│   ├── env.py                  # Alembic environment config
│   ├── script.py.mako          # Migration template
│   └── versions/               # Migration scripts
│       ├── 001_initial_schema.py
│       └── ...
├── app/
│   ├── config.py
│   ├── database.py
│   ├── models/
│   │   ├── db_models.py    # User, UserIntegration tables
│   │   └── schemas.py      # RegisterRequest, LoginRequest, TokenResponse, UserProfile
│   ├── routes/
│   │   ├── auth.py         # POST /register, POST /login, POST /refresh, GET /me
│   │   └── integrations.py # GET /integrations (list user's connected services)
│   └── services/
│       ├── jwt_service.py  # Issue/validate JWT (HS256, 24h expiry)
│       └── user_service.py # User CRUD, password hashing (bcrypt)
```

**API contract:**
```
POST /auth/register          → { email, password, name } → { access_token, refresh_token }
POST /auth/login             → { email, password }       → { access_token, refresh_token }
POST /auth/refresh           → { refresh_token }         → { access_token }
GET  /auth/me                → (Bearer token)            → { id, email, name, integrations[] }
GET  /auth/integrations      → (Bearer token)            → [{ service, status, connected_at }]
```

**JWT payload:**
```json
{
  "sub": "user_id",
  "email": "user@example.com",
  "iat": 1234567890,
  "exp": 1234654290
}
```

**Database:** PostgreSQL `auth_service` database with tables: `users`, `user_integrations`

---

## Phase 3: API Gateway

**Goal:** Single entry point that validates JWTs and routes to microservices.

**Two sub-phases:**

### Phase 3a: Nginx-Based Gateway (Quick Win)

Update existing `nginx.template` to add:
- JWT validation via `ngx_http_auth_jwt_module` or `auth_request` to auth-service
- Route mapping: `/api/slack/*` → `slack-service:8001`, `/api/github/*` → `github-service:8002`, etc.
- Rate limiting via `limit_req_zone`
- Add `X-User-ID` and `X-User-Email` headers from validated JWT
- CORS headers for React frontend

**Modify:** `/saas-poc/nginx.template` and `/saas-poc/deploy.sh`

### Phase 3b: Dedicated Gateway Service (Later)

**Create:** `/saas-poc/gateway/` (FastAPI or Kong)

```
gateway/
├── main.py
├── requirements.txt
├── app/
│   ├── config.py           # Route table, rate limit config
│   ├── middleware/
│   │   ├── jwt_auth.py     # Validate JWT, attach user context
│   │   ├── rate_limit.py   # Per-user/per-service rate limiting
│   │   └── cors.py         # CORS configuration
│   └── routes/
│       └── proxy.py        # Dynamic proxy to microservices
```

**Route configuration:**
```yaml
routes:
  - path: /api/slack/*       → slack-service:8001    (strip /api/slack)
  - path: /api/github/*      → github-service:8002   (strip /api/github)
  - path: /api/notion/*      → notion-service:8003   (strip /api/notion)
  # ... 36 services
  - path: /api/auth/*        → auth-service:8000     (strip /api/auth, no JWT required)
```

---

## Phase 4: Convert Microservices (Pilot: Slack, GitHub, Notion)

**Goal:** Convert 3 apps from HTML-serving to pure REST JSON APIs. Establish the pattern, then repeat for remaining 33.

### Per-service conversion steps:

#### 4.1 Remove HTML/Template dependencies
- Delete `app/templates/` directory
- Delete `app/static/` directory
- Remove `Jinja2Templates`, `StaticFiles` from `main.py`
- Remove `python-multipart` dependency (no more form data)

#### 4.2 Convert `app/routes/auth.py` to REST
**Before (HTML):**
```python
@router.get("/auth/login")
async def login(request: Request):
    return RedirectResponse(url=oauth_url)

@router.get("/auth/callback")
async def callback(request: Request, code: str, state: str):
    # exchange token, store in session
    return RedirectResponse(url="/dashboard")
```

**After (REST):**
```python
@router.get("/oauth/url")
async def get_oauth_url(request: Request):
    user_id = request.headers.get("X-User-ID")  # From gateway
    state = generate_state(user_id)
    return {"oauth_url": build_oauth_url(state), "state": state}

@router.post("/oauth/callback")
async def oauth_callback(payload: OAuthCallbackRequest,

---

# Production Architecture
# Production Architecture Recommendations

This document outlines the recommended architecture for deploying the cost optimizer tools in production.

## Recommendation: Microservices + API Gateway

The microservices approach is recommended over a monolith. Here's why and how to structure it:

```
┌─────────────────────────────────────────────────────────────────────┐
│                        React Frontend                                │
│                    (Single SPA, handles UI)                         │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         API Gateway                                  │
│  - Authentication (your app's JWT)                                  │
│  - Route mapping (/api/slack/*, /api/notion/*, etc.)               │
│  - Rate limiting                                                    │
│  - Request/response transformation                                  │
└─────────────────────────────────────────────────────────────────────┘
                                │
        ┌───────────┬───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
   │  Slack  │ │ Notion  │ │ZoomInfo │ │ GitHub  │ │  ...    │
   │ Service │ │ Service │ │ Service │ │ Service │ │         │
   └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
```

## Why Microservices Over Monolith

| Concern | Microservices | Monolith |
|---------|--------------|----------|
| **Testing scope** | Only test affected service | Full regression needed |
| **Deployment risk** | Isolated failures | One bug affects all |
| **Scaling** | Scale hot services independently | Scale everything |
| **Tech debt** | Contained per service | Spreads across codebase |
| **Team velocity** | Parallel development | Coordination overhead |
| **Dependency conflicts** | Isolated dependencies | Version conflicts |

The concern about testing is valid - with 10+ integrations, a monolith change requires testing all OAuth flows, all API interactions, etc.

## API Gateway: Yes, Add It

The gateway provides critical value:

### 1. Centralized Authentication
```
┌──────────────────────────────────────────────────────┐
│                    API Gateway                        │
│                                                       │
│  1. Validate YOUR app's JWT (user session)           │
│  2. Attach user context to request                   │
│  3. Forward to appropriate microservice              │
│                                                       │
│  Microservices trust gateway, no auth logic needed   │
└──────────────────────────────────────────────────────┘
```

### 2. OAuth Callback Handling

```
OAuth Flow with Gateway:

1. React: User clicks "Connect Slack"
2. React: Redirects to Slack OAuth with callback URL:
   https://yourapp.com/oauth/callback/slack

3. Slack: User authorizes, redirects back to callback

4. React: Receives callback at /oauth/callback/slack
   - Extracts code & state from URL
   - POSTs to gateway: POST /api/slack/auth/callback

5. Gateway:
   - Validates user session
   - Forwards to Slack microservice

6. Slack Service:
   - Exchanges code for token
   - Stores encrypted token
   - Returns success
```

### 3. Simplified Microservices

Without gateway auth, each microservice needs:
```python
# ❌ Without gateway - duplicated in every service
@router.post("/analyze")
async def analyze(request: Request, token: str = Depends(verify_jwt)):
    # Validate JWT
    # Check permissions
    # Rate limit
    # Then do actual work...
```

With gateway:
```python
# ✅ With gateway - trust the gateway
@router.post("/analyze")
async def analyze(request: Request):
    user_id = request.headers.get("X-User-ID")  # Gateway adds this
    # Just do the work, auth is han

---

# Current State
- 51 vendors tracked
- 51 POC apps built
- 26 microservices deployed
- 26 Helm charts created

Milestones

Phase 1

Shared Python Library (`blokid_common`) complete

**Goal:** Extract duplicated code from 36 apps into a shared installable package.

shared/blokid_common/ exists

Achieved: 2026-03-05

Phase 2

Auth Service complete

**Goal:** Centralized user management and JWT issuance. All other services trust JWTs from this service.

auth-service/ exists

Achieved: 2026-03-05

Phase 3

API Gateway complete

**Goal:** Single entry point that validates JWTs and routes to microservices.

gateway/ exists

Achieved: 2026-03-05

Phase 4

Convert Microservices (Pilot: Slack, GitHub, Notion) in_progress

**Goal:** Convert 3 apps from HTML-serving to pure REST JSON APIs. Establish the pattern, then repeat for remaining 33.

26 microservices migrated