Geek Cafe SaaS SDK

⚠️ Beta Notice: This library is under active development. Breaking changes may occur until we reach a stable 1.0 release. We recommend pinning to specific versions in production.

✨ New in v0.78.0: Automatic security model, simplified handler patterns, and comprehensive pattern guides!

Test Coverage

Tests Coverage

Overall Coverage: 78.1% (20284/25964 statements)

Coverage Summary

Metric	Value
Total Statements	25,964
Covered Statements	20,284
Missing Statements	5,680
Coverage Percentage	78.1%
Total Tests	1929
Test Status	✅ All Passing

Files Needing Attention (< 80% coverage)

Coverage	Missing Lines	File
0.0%	2	`modules/executions/handlers/__init__.py`
0.0%	2	`modules/executions/handlers/get_status/__init__.py`
0.0%	2	`modules/feature_flags/models/__init__.py`
0.0%	2	`modules/feature_flags/services/__init__.py`
0.0%	2	`modules/file_system/handlers/unarchive/__init__.py`
0.0%	10	`modules/executions/handlers/get_status/app.py`
0.0%	12	`modules/file_system/handlers/unarchive/app.py`
0.0%	21	`core/models/base_async_event_model.py`
0.0%	115	`modules/feature_flags/models/feature_flag.py`
0.0%	135	`modules/executions/handlers/workflow_step_handler.py`

... and 60 more files with < 80% coverage

Running Tests

# Run all tests with coverage
./run_unit_tests.sh

# View detailed coverage report
open reports/coverage/index.html

Last updated: 2026-01-01 15:14:41

Description

Geek Cafe Services is a production-ready, enterprise-grade library that provides reusable database services specifically designed for multi-tenant SaaS applications. Built on top of AWS DynamoDB, this library offers a prescriptive approach to building scalable, maintainable backend services with consistent patterns and best practices.

Why Geek Cafe Services?

🏗️ Consistent Architecture: All services follow the same proven patterns for CRUD operations, error handling, and access control
🔒 Multi-Tenant by Design: Built-in tenant isolation ensures secure data separation across customers
⚡ DynamoDB Optimized: Leverages DynamoDB's strengths with efficient GSI indexes and query patterns
🛡️ Production Ready: Comprehensive error handling, logging, pagination, and batch operations
🧪 Fully Tested: 100% test coverage with comprehensive test suites for reliability
📖 Well Documented: Extensive documentation with practical examples and best practices

Perfect For

SaaS Applications requiring multi-tenant data isolation
Serverless Architectures built on AWS Lambda and DynamoDB
Teams wanting consistent, proven patterns across services
Rapid Development with pre-built, tested service components

Installation

# Clone the repository
git clone https://github.com/geekcafe/geek-cafe-services.git
cd geek-cafe-services

# Setup the development environment
./pysetup.sh

# Install dependencies
pip install -r requirements.txt

Quick Start

For Lambda Handlers (Recommended)

from geek_cafe_saas_sdk.lambda_handlers import create_handler
from geek_cafe_saas_sdk.modules.workflows.services import WorkflowService

# Module-level handler for connection pooling
handler_wrapper = create_handler(
    service_class=WorkflowService,
    convert_request_case=True,   # camelCase → snake_case
    convert_response_case=True   # snake_case → camelCase
)

def lambda_handler(event, context, injected_service=None):
    return handler_wrapper.execute(event, context, business_logic, injected_service)

def business_logic(event, service):
    # Your business logic - security and case conversion are automatic!
    body = event.get("parsed_body") or {}
    result = service.create(**body)
    return {"execution_id": result.data.id, "status": "created"}

For Direct Service Usage

from geek_cafe_saas_sdk.modules.messaging.services import MessageService
from geek_cafe_saas_sdk.core import AnonymousContextFactory

# Create request context
context = AnonymousContextFactory.create_test_context(
    user_id='user_123',
    tenant_id='tenant_456'
)

# Initialize service with context
service = MessageService(request_context=context)

# Create a message - security is automatic!
result = service.create(
    type="notification",
    content={"title": "Welcome!", "body": "Thanks for joining."}
)

if result.success:
    print(f"Created message: {result.data.id}")

📖 Complete Quick Start Guide

Available Services

🚀 Lambda Handler Wrappers (NEW in v0.2.0)

Purpose: Eliminate 70-80% of boilerplate code in AWS Lambda functions

Key Capabilities:

✅ Automatic API key validation from environment
✅ Request body parsing and camelCase → snake_case conversion
✅ Service initialization with connection pooling for warm starts
✅ Built-in CORS and error handling
✅ User context extraction from authorizers
✅ Service injection for easy testing
✅ Support for public and secured endpoints

Available Handlers:

ApiKeyLambdaHandler - API key validation (most common)
PublicLambdaHandler - No authentication (config endpoints)
BaseLambdaHandler - Extensible base for custom handlers

Quick Example:

from geek_cafe_saas_sdk.lambda_handlers import ApiKeyLambdaHandler
from geek_cafe_saas_sdk.vote_service import VoteService

# All boilerplate handled in 3 lines
handler = ApiKeyLambdaHandler(
    service_class=VoteService,
    require_body=True,
    convert_case=True
)

def lambda_handler(event, context):
    return handler.execute(event, context, create_vote)

def create_vote(event, service, user_context):
    # Just your business logic - everything else is handled!
    payload = event["parsed_body"]  # Already parsed & converted
    return service.create_vote(
        tenant_id=user_context.get("tenant_id", "anonymous"),
        user_id=user_context.get("user_id", "anonymous"),
        **payload
    )

Use Cases: Any AWS Lambda function with API key auth, reducing code by 70-80% while maintaining all functionality

📖 Complete Lambda Handlers Documentation

📧 MessageService

Purpose: Complete message and notification management system

Key Capabilities:

✅ Full CRUD operations with tenant isolation
✅ Flexible JSON content storage for any message type
✅ Efficient querying by user, tenant, and message type
✅ Automatic audit trails and timestamps
✅ Built-in access control and validation

Use Cases: User notifications, system alerts, communication logs, announcement management

🗳️ Voting Services Suite

Purpose: Complete voting and rating system with real-time aggregation

Architecture: Three interconnected services working together:

VoteService

✅ Individual vote management with automatic upsert behavior
✅ One vote per user per target enforcement
✅ Support for up/down votes or custom vote types
✅ Comprehensive querying by user, target, and tenant

VoteSummaryService

✅ Pre-calculated vote totals for instant retrieval
✅ Target-based optimization for high-performance lookups
✅ Metadata tracking (last tallied timestamp, vote counts)
✅ Tenant-scoped summary management

VoteTallyService

✅ Intelligent vote aggregation with pagination support
✅ Batch processing for multiple targets
✅ Stale target detection and automated re-tallying
✅ Comprehensive error handling and resilience

Use Cases: Product ratings, content voting, feedback systems, community polls, recommendation engines

Documentation

📖 Documentation Index - Complete documentation roadmap

Core Pattern Guides (Start Here)

DatabaseService Patterns ⭐ - CRUD, security, queries, models
Lambda Handler Patterns ⭐ - API Gateway & SQS handlers
Security Architecture - Automatic security model
Case Conversion Guide - camelCase ↔ snake_case

Module-Specific Guides

File System - File management
Workflows - Execution & step models
Messaging - Chat & contact threads
Events - Event management
Analytics - Analytics tracking

Configuration & Architecture

Configuration Guide - Environment variables
Architecture Overview - System design
Service Pool Telemetry - Connection pooling

Core Features

🏛️ Enterprise Architecture

Multi-Tenant by Design: Complete tenant isolation with automatic access control
Consistent Patterns: All services follow identical CRUD interfaces and conventions
Scalable Design: Built for high-throughput, multi-customer SaaS applications

🔧 Developer Experience

Type Safety: Full Python type hints for better IDE support and fewer bugs
Comprehensive Testing: 100% test coverage with realistic test scenarios
Rich Documentation: Detailed API docs, examples, and best practices
Easy Integration: Simple initialization and consistent error handling

⚡ Performance & Reliability

DynamoDB Optimized: Efficient GSI indexes and query patterns for fast operations
Pagination Support: Handle large datasets without memory issues
Batch Operations: Process multiple items efficiently
Error Resilience: Graceful handling of partial failures and edge cases

🛡️ Production Ready

Structured Logging: AWS Lambda Powertools integration for observability
Comprehensive Validation: Input validation with detailed error messages
Access Control: Automatic tenant and user-based security enforcement
Audit Trails: Complete tracking of who did what and when

Environment Setup

# Required environment variables
export DYNAMODB_TABLE_NAME=your_table_name

# Optional AWS configuration (if not using IAM roles)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

Testing

# Run all tests
pytest tests/ -v

# Run specific service tests
pytest tests/test_message_service.py -v
pytest tests/test_vote_*_service.py -v

# Run with coverage
pytest tests/ --cov=geek_cafe_saas_sdk --cov-report=html

Project Structure

geek-cafe-services/
├── src/geek_cafe_saas_sdk/
│   ├── lambda_handlers/     # 🆕 Lambda handler wrappers (v0.2.0)
│   │   ├── base.py          # Base handler with common functionality
│   │   ├── api_key_handler.py    # API key validation handler
│   │   ├── public_handler.py     # Public (no auth) handler
│   │   └── service_pool.py       # Service connection pooling
│   ├── middleware/          # CORS, auth, error handling decorators
│   ├── utilities/           # Request/response helpers
│   ├── models/              # Data models with DynamoDB mapping
│   ├── *_service.py         # Service implementations
│   ├── database_service.py  # Base service class
│   └── service_result.py    # Standardized response wrapper
├── tests/                   # Comprehensive test suite
├── docs/                    # Detailed documentation
│   └── lambda_handlers.md   # 🆕 Lambda wrapper documentation
├── examples/                # Working code examples
│   └── lambda_handlers/     # 🆕 Handler examples
└── README.md               # This file

Contributing

We welcome contributions! Here's how to get started:

Fork the repository and create a feature branch
Follow the existing patterns - consistency is key
Add comprehensive tests for any new functionality
Update documentation for API changes
Submit a Pull Request with a clear description

Development Guidelines

Follow existing code style and patterns
Maintain 100% test coverage for new code
Update documentation for any API changes
Use meaningful commit messages
Test against multiple Python versions if possible

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

📖 Documentation: Complete docs
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Questions: Create an issue with the "question" label

Built with ❤️ for the SaaS development community

Metadata

Release files for geek-cafe-saas-sdk 0.311.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geek-cafe-saas-sdk 0.311.0
File	Size	Uploaded	Provenance
geek_cafe_saas_sdk-0.311.0.tar.gz	870.1 kB	Oct 20, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for geek-cafe-saas-sdk 0.311.0
File	Interpreter	ABI	Platform	Reset
geek_cafe_saas_sdk-0.311.0-py3-none-any.whl 955.0 kB Oct 20, 2026 Without provenance	Python 3	none	any	Details

Total release size: 1.8 MB

Release files / geek_cafe_saas_sdk-0.311.0.tar.gz

Download URL	geek_cafe_saas_sdk-0.311.0.tar.gz
Size	870.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`72af14aa3c1b99080fde12cb3c4e17a7beabc97af794a96f6472b289fecf6f72`
BLAKE2b-256 checksum How to use checksums	`f1f1cfe0419122b6821c121ca75d8094ed3a6d0a4b3bd87b8ff0bcc5fba8644c`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`

Release files / geek_cafe_saas_sdk-0.311.0-py3-none-any.whl

Download URL	geek_cafe_saas_sdk-0.311.0-py3-none-any.whl
Size	955.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cf194a65f4322ff625c97c03c29dba2ba053d75e965c054bc2c6aac7fcff4821`
BLAKE2b-256 checksum How to use checksums	`8b1ca9c25288bb440e523aab431dbfa4a95ca947e7316a6a871b7868258f8d92`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`

Security for geek-cafe-saas-sdk 0.311.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.