Architecture Layers
Detailed breakdown of each infrastructure layer and component connections
Architecture Layers
This section provides a detailed breakdown of each infrastructure layer, explaining how components connect and depend on each other within the AI SaaS Boilerplate.
Layer Overview
The platform follows a dependency-driven architecture where each layer builds upon the previous one:
Core Infrastructure → Business Logic → AI Services → Frontend
Each layer provides essential services that upper layers depend on, ensuring clean separation of concerns and maintainable code structure.
Frontend Layer
Next.js Web Application
The frontend layer handles user interface and client-side functionality through AWS Amplify hosting with server-side rendered React application built with JavaScript and Tailwind CSS.
| Component | File Location | Purpose |
|---|---|---|
| Next.js Deployment | lib/frontend/nextjs_stack.py | AWS Amplify hosting and GitHub integration |
| Configuration Management | lib/frontend/amplify_config_stack.py | Environment variables and API endpoint configuration |
| User Settings API | lib/frontend/api/user_settings_stack.py | Frontend-specific user preferences and profile management |
Frontend Dependencies
The frontend layer connects to all other infrastructure layers:
- Authentication: Cognito user pools for login/registration
- API Access: All AI service endpoints and business logic APIs
- Storage: S3 bucket access for file uploads and downloads
- Real-time Data: AppSync GraphQL for live credit balance updates
API Layer
Request Routing & Authentication
Each component uses API Gateway for HTTP request routing with standardized authentication and CORS configuration.
| Service Category | Authentication Method | Key Features |
|---|---|---|
| AI Services | Cognito User Pool Authorization | JWT token validation, rate limiting |
| Payment Services | Cognito + Stripe Integration | Subscription management, billing |
| Public APIs | IAM Authorization | Pricing information |
| User Management | Cognito User Pool Authorization | Profile, settings, preferences |
Service-Specific API Patterns
All AI services follow consistent API Gateway patterns with standardized request/response handling, authentication integration, and error management.
Service Layer
AI Services Architecture
The service layer implements all AI functionality through Lambda functions with consistent patterns for authentication, credit management, and error handling.
| Service Category | File Location | Services Included | External Dependencies |
|---|---|---|---|
| Document Services | lib/services/document/ | PDF Chat, OCR, Markdown Conversion | OpenAI API, AWS Textract |
| Image Services | lib/services/image/ | AI Generation, Style Transfer, Background Operations | AWS Bedrock |
| Video Services | lib/services/video/ | YouTube Chat, Video Summarization | OpenAI API, YouTube API |
Core Services Layer
Authentication System
AWS Cognito provides comprehensive user management with Google OAuth integration and automated user onboarding.
| Authentication Component | File Location | Functionality |
|---|---|---|
| Cognito User Pool | lib/core/auth/cognito_stack.py | User registration, login, OAuth integration |
| Redirect Patching | lib/core/auth/patch_redirects_stack.py | Post-deployment callback URL updates |
| Email Templates | lib/core/auth/templates/ | Custom verification and welcome emails |
User Onboarding Flow: New users automatically receive 20 credits (BASIC plan), profile initialization, and email verification.
Credits & Billing System
The credit system manages user balances, service usage, and subscription billing through real-time GraphQL APIs.
| Credits Component | File Location | Purpose |
|---|---|---|
| Credit Management API | lib/business/credits/credit_api_stack.py | AppSync GraphQL API for real-time credit tracking |
| Credit Processing | lib/business/credits/credit_handler_stack.py | Usage deduction and monthly distribution |
| Service Pricing | lib/business/credits/service_pricing_stack.py | Dynamic pricing configuration per AI service |
| AppSync Schema | lib/business/credits/appsync/schema.graphql | GraphQL type definitions and operations |
Payment Processing
Stripe integration handles all payment operations through dedicated APIs with webhook processing for real-time event handling.
| Payment Component | File Location | Functionality |
|---|---|---|
| Payment Integration | lib/business/payments/payment_integration_stack.py | Complete Stripe integration with three APIs |
| Webhook API | Included in payment integration | Real-time Stripe event processing |
| Pricing API | Included in payment integration | Public subscription plan information |
| Payment Management API | Included in payment integration | Subscription and billing operations |
Core Infrastructure
| Infrastructure Component | File Location | Purpose |
|---|---|---|
| Storage Management | lib/core/storage/storage_stack.py | S3 bucket creation with Cognito integration |
| Configuration Management | lib/core/config.py | Environment variable validation and AWS setup |
| Event Scheduling | lib/core/scheduler/scheduler_role_stack.py | EventBridge for automated tasks |
| Utility Functions | lib/core/utils/ | Shared utilities, API templates, secure parameters |
Data Storage Layer
Database Structure
| Data Store | Purpose | Key Tables/Buckets |
|---|---|---|
| DynamoDB | Structured data | User credits, payment history, service pricing cache |
| S3 | File storage | User uploads, generated content, temporary processing files |
| Parameter Store | Secure configuration | API keys, webhook secrets, service credentials |
Storage Organization
| Storage Type | Location Pattern | Access Control |
|---|---|---|
| Public Files | s3://bucket/public/* | Public read access |
| User Files | s3://bucket/private/{user-id}/* | User-specific via Cognito |
Component Dependencies
Next Steps
Now that you understand the detailed architecture:
- Explore the Backend section for service implementation details
- Review the Frontend section for user interface architecture
- Check Customization options for modifying the platform