Backend Overview¶

The Certana Backend is a production-grade FastAPI application written in Python that handles:

Image upload and processing
ML-powered watermarking and fingerprinting
Blockchain integration with Solana
User authentication and authorization
Organization and API key management
Usage tracking and quota enforcement
Content verification

Architecture Highlights¶

Core Stack¶

Framework: FastAPI 0.115.0 with async/await
Database: PostgreSQL with SQLAlchemy ORM
Authentication: JWT + OAuth2 + API Keys
Rate Limiting: SlowAPI for request throttling
Logging: Structured logging with structlog

Key Features¶

1. Async Architecture¶

Non-blocking database operations with AsyncPG
Concurrent request handling
Efficient resource utilization

2. ML Integration¶

PyTorch-based watermarking (Track A, B, C)
CLIP embeddings for content fingerprinting
DINO v2 for structural fingerprinting
Invisible watermark library

3. Blockchain Integration¶

Solana RPC integration
Program ID-based commitment storage
Transaction signing and verification
Anchor framework support

4. Storage Options¶

IPFS for distributed storage
Filecoin via Lighthouse for long-term storage
AWS S3 for CDN-backed access
Multiple storage providers support

5. Security¶

Cryptographic master key management
Encryption for sensitive data
CORS and rate limiting
Input validation with Pydantic

Directory Structure¶

backend/
├── src/
│   ├── main.py                  # Application entry point
│   ├── api/                     # API endpoint modules
│   │   ├── assets.py            # Asset CRUD operations
│   │   ├── verification.py      # Image verification
│   │   ├── auth.py              # Authentication endpoints
│   │   ├── blockchain.py        # Blockchain operations
│   │   ├── storage.py           # Storage management
│   │   ├── organizations.py     # Org management
│   │   ├── api_keys.py          # API key management
│   │   └── ...
│   ├── models/                  # SQLAlchemy ORM models
│   │   ├── user.py              # User model
│   │   ├── asset.py             # Asset model
│   │   ├── watermark.py         # Watermark model
│   │   ├── fingerprint.py       # Fingerprint model
│   │   └── ...
│   ├── schemas/                 # Pydantic validation schemas
│   ├── services/                # Business logic services
│   │   ├── asset_service.py     # Asset processing
│   │   ├── blockchain_service.py # Blockchain ops
│   │   ├── storage_service.py   # Storage ops
│   │   └── ...
│   ├── core/                    # Core utilities
│   │   ├── config.py            # Settings management
│   │   ├── database.py          # DB session management
│   │   ├── auth.py              # Auth utilities
│   │   └── logging.py           # Logging setup
│   ├── watermarking/            # Watermarking algorithms
│   ├── fingerprinting/          # Fingerprinting algorithms
│   └── __pycache__/
├── alembic/                     # Database migrations
├── config/                      # Wallet and key configs
├── docs/                        # Swagger OpenAPI docs
├── tests/                       # Unit and integration tests
├── Dockerfile
├── requirements.txt
├── alembic.ini
└── docker-compose.yml

Main API Endpoints¶

Authentication¶

POST /v1/auth/register - User registration
POST /v1/auth/login - User login
POST /v1/auth/refresh - Refresh JWT token
POST /v1/auth/logout - User logout

Assets¶

POST /v1/assets/ - Upload new asset
GET /v1/assets/ - List user's assets
GET /v1/assets/{id}/ - Get asset details
PATCH /v1/assets/{id}/ - Update asset metadata
DELETE /v1/assets/{id}/ - Delete asset

Verification¶

POST /v1/verify/ - Verify image authenticity
POST /v1/verify/batch - Batch verification
GET /v1/verify/history - Verification history

Blockchain¶

POST /v1/blockchain/commit - Create blockchain commitment
GET /v1/blockchain/commitment/{id} - Get commitment details
GET /v1/blockchain/verify/{tx_hash} - Verify transaction

Organizations¶

POST /v1/organizations/ - Create organization
GET /v1/organizations/ - List organizations
GET /v1/organizations/{id}/ - Get org details
PATCH /v1/organizations/{id}/ - Update organization

API Keys¶

POST /v1/api-keys/ - Create API key
GET /v1/api-keys/ - List API keys
POST /v1/api-keys/validate - Validate API key
DELETE /v1/api-keys/{id} - Delete API key

Configuration¶

All settings are managed via environment variables in .env:

# Application
VERSION=1.0.0
ENVIRONMENT=development
SECRET_KEY=your-secret-key
MASTER_KEY=your-master-key

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/certana
DATABASE_POOL_SIZE=20

# Redis
REDIS_URL=redis://localhost:6379/0

# Solana
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_PROGRAM_ID=CertXXXXXXX...

# Storage
IPFS_API_URL=/ip4/127.0.0.1/tcp/5001
AWS_ACCESS_KEY_ID=your-key
S3_BUCKET_NAME=your-bucket

# OAuth
GOOGLE_CLIENT_ID=...
GITHUB_CLIENT_ID=...

See Installation Guide for detailed setup instructions.