# 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

```bash
# 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:**
```python
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