CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Fission-based serverless Python microservice for AI user administration. It runs on Kubernetes with PostgreSQL as the data store.

Stack: Python 3.10, Flask, Fission FaaS, PostgreSQL, Pydantic

Build & Deploy Commands

# Build (installs Python dependencies)
cd apps && ./build.sh

# Deploy to Kubernetes (reconciles all Fission specs)
fission spec apply

# Watch and redeploy on changes
fission spec apply --watch

Architecture

Two Fission functions handle all HTTP endpoints:

Function	Routes	Operations
`ai-admin-filter-create-user`	`GET/POST /ai/admin/users`	Filter users with pagination, create new user
`ai-admin-update-delete-user`	`PUT/DELETE /ai/admin/users/{UserID}`	Update/delete user by ID

Source structure (apps/):

filter_insert.py - GET (filter) & POST (create) handler with main() entry point
update_delete.py - PUT (update) & DELETE handler with main() entry point
schemas.py - Pydantic models (AiUserCreate, AiUserUpdate) for validation
helpers.py - Database connection, K8s secrets, CORS headers, utilities
vault.py - PyNaCl symmetric encryption (encrypt_vault/decrypt_vault)

Deployment configs (.fission/):

local-deployment.json, dev-deployment.json, test-deployment.json, staging-deployment.json, deployment.json

Fission specs (specs/):

env-work-py.yaml - Python 3.10 runtime environment
package-ai-work.yaml - Build configuration
Function and HTTP trigger definitions

Key Patterns

Error handling:

try:
    conn = init_db_connection()
    # operations
except ValidationError as e:
    return jsonify({"errorCode": "VALIDATION_ERROR", "details": e.errors()}), 400, CORS_HEADERS
except IntegrityError:
    return jsonify({"errorCode": "DUPLICATE_TAG", ...}), 409, CORS_HEADERS
finally:
    if conn:
        conn.close()

Dynamic SQL filtering: Build conditions list and values dict, join with AND for WHERE clause.

Fission route params: Extracted from headers (e.g., X-Fission-Params-UserID).

Concurrent updates: Uses PostgreSQL row-level locking (FOR UPDATE).

Secrets & Configuration

Secrets are read from K8s mounted volumes via helpers.get_secret() and helpers.get_config(), not environment variables. PostgreSQL credentials come from the fission-ai-work-env secret.

Function Configuration

Executor: newdeploy (dedicated pod per function)
Timeout: 300 seconds
Min/Max Scale: 1
Concurrency: 500 requests per pod

2.6 KiB Raw Permalink Blame History