geek-cafe-saas-sdk 0.225.0

Base Reusable Services for SaaS

Geek Cafe Services

⚠️ 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

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:

1. Fork the repository and create a feature branch
2. Follow the existing patterns - consistency is key
3. Add comprehensive tests for any new functionality
4. Update documentation for API changes
5. 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