ToraBeta

Serverless, event-driven architecture designed for low operational overhead and horizontal scalability.

• 1. Client (Mobile App): User interaction, UI design system, state, and client-side logic. (Stack: React Native + Expo, Expo Router, NativeWind, Zustand, Axios & Zod)
• 2. Server (Backend API & AI): Application processing, validation, database querying, and direct orchestration with artificial intelligence. (Stack: Hono Framework, Drizzle ORM, AWS Bedrock SDK [Amazon Nova Lite & Amazon Titan], Zod Validation)
• 3. Data (Database): Data persistence, relational integrity, and planned semantic indexing. (Stack: Neon Postgres, pgvector extension [Upcoming])
• 4. DevOps & Infra (Deployment & Foundation): How the serverless application is built, provisioned, and hosted in the cloud. (Stack: Docker, AWS Lambda, Terraform, ECR, CloudWatch, GitHub Actions)

Strictly serverless, event-driven network deployment mapping out cloud boundaries and secure access paths across AWS and Neon.

• 1. Client / Edge Domain: The user's mobile app (Expo/React Native Client) communicating over secure HTTPS directly to AWS.
• 2. AWS Cloud Domain: Containerized compute, logging, and serverless AI. Connects Amazon ECR (Docker registry), AWS Lambda (Hono serverless compute), Lambda Function URLs (cost-controlled public endpoints with built-in CORS), AWS IAM execution roles (secure, keys-free access to Bedrock APIs), AWS Bedrock (Serverless Nova Lite LLM), and Amazon CloudWatch (automated execution monitoring).
• 3. Neon Cloud Domain: Separate serverless database cloud hosting the primary Neon PostgreSQL instance, connected securely via PostgreSQL TCP connection.

Lambda-first architecture optimized for stateless execution and cost efficiency.

• Stateless AWS Lambda functions for all core API operations
• Event-driven workout ingestion pipeline via chat requests
• No persistent server layer (eliminates ECS/EKS overhead)
• Cold start considerations mitigated via lightweight handlers
• Separation of concerns between auth, chat, and analytics functions

Cost-controlled LLM pipeline for natural language workout parsing and coaching feedback.

• AWS Bedrock (Nova Lite) used for structured workout extraction
• Token-based cost model with credit abstraction layer
• Input/output separation for cost tracking and optimization
• Prompt engineering tuned for deterministic workout parsing
• Feedback generation tied to skill tree progression rules

Decoupled ingestion pipeline ensuring reliability and scalability under variable user load.

• User submits workout via chat message
• Lambda processes and forwards to Bedrock for parsing
• Structured output persisted in Neon Postgres
• Optional vector embedding generation for memory layer
• Asynchronous design avoids blocking user interaction

Hybrid relational + vector storage model optimized for structured tracking and semantic recall.

• Neon Postgres stores users, workouts, credits, and progression state
• Vector embeddings enable long-term training memory retrieval
• Schema designed around movement categories and skill tree states
• Efficient read patterns for dashboard and analytics queries
• Separation of transactional vs semantic data storage

System designed for horizontal scaling without infrastructure rework.

• Lambda auto-scales per request load
• Bedrock inference scales independently of application layer
• Database scaling delegated to Neon serverless Postgres
• Stateless backend ensures no session affinity requirements
• Chat-driven workload naturally batches into short-lived executions

Architecture explicitly optimized around per-token LLM economics and serverless billing models.

• LLM costs abstracted into credit system (1 credit per ~3,000 tokens)
• Bedrock dominates variable costs (primary scaling risk factor)
• Lambda and Cloudflare operate near-zero cost at small scale
• Neon Postgres free tier minimizes baseline infrastructure cost
• Designed for predictable margin per AI interaction

Minimal attack surface design using managed services and strict separation of concerns.

• No exposed servers or persistent compute instances
• All API access routed through authenticated Lambda endpoints
• Cloudflare provides TLS termination and edge protection
• Neon handles database isolation and managed security patching
• Bedrock inference executed within AWS-managed secure boundary

Lightweight edge authentication proxy using Cloudflare Workers as a network-level trust boundary, ensuring all traffic must pass through Cloudflare before reaching the API.

• Intercepts all API requests — every client request hits the Cloudflare Worker first (edge location) before reaching the origin.
• Injects a shared secret header — the worker signs the request using a token bound to the worker's environment.
• Forwards to the origin server — clones the original request and proxies it to the backend endpoint.
• Origin validates the signature — the backend checks the header with a timing-safe comparison to ensure the request came through the edge proxy, not directly.
• Infrastructure managed via Terraform — the worker script, environment bindings, and public edge subdomain are fully provisioned as code.

Development (Local) vs. Production (Cloud) environments engineered for hot-reloading development speed and high-scale cloud execution.

• 1. Development Environment (Local Host): Fast, hot-reloading sandbox. Client runs locally via Expo Go on Wi-Fi IP, server API runs via tsx watch directly on Node.js (localhost:3000), database connects to Neon Dev Postgres, and Bedrock calls use a local .env file containing AWS credentials.
• 2. Production Environment (Cloud Host): Secure, serverless deployment. Client is built via Expo EAS for app stores, server API is compiled and packaged as a Docker container running on AWS Lambda with a Function URL (HTTPS), database connects to Neon Prod Postgres, and Bedrock calls authorize through IAM roles managed by Terraform (/infrastructure).

Containerized backend components for consistent runtime behavior across environments.

• Docker used for packaging backend services and dependencies
• Consistent local and cloud execution environments
• ECR-compatible image builds for AWS deployment workflows
• Isolated runtime environments for reproducibility
• Simplifies dependency management for Lambda-adjacent services

Fully automated GitHub Actions workflow packaging backend updates as containerized Docker images and deploying serverlessly to AWS Lambda on every code push.

• 1. Git Trigger Check: Automatically initiated on any push to the 'main' branch that changes files in the 'server/**' directory.
• 2. Runner Initialization: Launches an isolated Ubuntu Linux virtual runner environment and checkouts the active repository branch.
• 3. AWS Authentication: Connects to AWS securely via decrypted GitHub Secrets and logs into your private AWS Elastic Container Registry (ECR).
• 4. Docker Compilation & Tagging: Compiles the TypeScript Hono API and builds the Docker container from public.ecr.aws/lambda/nodejs:20, tagging it with both the commit SHA and 'latest'.
• 5. ECR Image Ingestion: Uploads and registers both image tags to your AWS repository.
• 6. Serverless Cloud Deploy: Executes an asynchronous aws lambda update-function-code command via the AWS CLI to point the active Lambda function to the newly uploaded container image.