Forem: Nauman Tanwir

Introducing GuardScan: 100% Free, Privacy-First AI Code Review & Security Scanning CLI

Nauman Tanwir — Mon, 17 Nov 2025 03:02:20 +0000

Introducing GuardScan: Privacy-First Security Scanning & AI Code Review

Hey dev.to community! 👋

I'm excited to share GuardScan v1.0, a tool I built to solve a problem I ran into over and over again: finding a security scanner and AI reviewer that's strong, affordable, and respects developer privacy.

The Problem

Most security and code review tools fall short:

🚫 Expensive
🚫 Privacy concerns
🚫 Usage limits
🚫 Vendor lock-in

The Solution: GuardScan

GuardScan is a free, open-source CLI that offers full security scanning and AI-powered code review while keeping everything on your machine.

Core Principles

1. Always Free

No credit system
No subscriptions
No enterprise-only features
Unlimited repositories

2. Privacy-First

Never upload your source code
Offline static analysis
Optional, anonymized telemetry
All code stays local

3. Bring Your Own Key (BYOK)

Use OpenAI, Claude, Gemini, or local AI via Ollama
Pay your provider directly
GuardScan charges nothing

Quick Start

### Install globally
npm install -g guardscan

### Initialize
guardscan init

### Run security scan (offline)
guardscan security

### Configure AI provider (optional)
guardscan config

### Run AI-enhanced review
guardscan run

What Can GuardScan Do?

🔒 Security Scanning (Free & Offline)

Built-in scanners:

Secrets detection
Dependency vulnerabilities
OWASP Top 10 checks
Docker security
Infrastructure as Code analysis
API security
Code metrics
Code smells
License compliance

🤖 AI-Enhanced Features (BYOK)

guardscan explain <file>
guardscan review <file>
guardscan commit
guardscan docs <file>
guardscan test-gen <file>
guardscan refactor <file>
guardscan threat-model
guardscan migrate
guardscan chat

🌍 Language Support

AST parsers for:

TypeScript / JavaScript
Python
Java
Go
Rust
Ruby
PHP
C#

Architecture: Privacy by Design

┌─────────────────────────────────┐
│      YOUR MACHINE               │
│                                 │
│  ┌─────────────────────────┐    │
│  │   GuardScan CLI         │    │
│  │   • Static Analysis     │    │
│  │   • Security Scanning   │    │
│  │   • AI Integration      │    │
│  └─────────────────────────┘    │
│             │                   │
└─────────────┼───────────────────┘
              │
    ┌─────────┴─────────┐
    │                   │
    ▼                   ▼
┌─────────────┐   ┌──────────────┐
│ Your AI     │   │ Telemetry    │
│ Provider    │   │ (Optional)   │
│ (Optional)  │   │              │
└─────────────┘   └──────────────┘

Your code never leaves your machine.

Real-World Example

Let’s say you have a 10k-line TypeScript project.

Install and set up

npm install -g guardscan
guardscan init

Run a free security scan

guardscan security

Output:

Secrets scan: 3 issues found

Dependency scan: 12 vulnerabilities

OWASP scan: 5 potential issues

Code quality: 89/100

Report saved: security-report.md

Configure AI

guardscan config

Run AI review

guardscan run

Output:

Analyzing codebase...

Found 47 improvement suggestions

Identified 8 security concerns

Report saved: review-report.md

Total cost:

GuardScan: $0
Static analysis: $0
AI review (with Ollama): $0

Technology Stack

CLI (34k+ LOC):

TypeScript 5.3+
Node.js 18+
Commander.js
Jest test suite

Comparison

Feature	GuardScan	SonarQube	Snyk	GitHub Copilot
Price	Free	Limited / Paid	Paid	Paid
Privacy	Local	Cloud upload	Cloud upload	Cloud upload
Offline	Yes	No	No	No
AI Provider	Any	N/A	Proprietary	OpenAI only
Open Source	MIT	LGPL	No	No
Usage Limits	Unlimited	Yes	Yes	Yes

Roadmap

GitHub Actions integration
GitLab CI/CD support
VSCode extension
Web UI for reports
More language parsers (Swift, Kotlin)
Custom rule engine upgrades

Contributing

GuardScan is open source (MIT License) and contributions are welcome!

Report bugs: GitHub Issues
Request features: GitHub Issues
Submit PRs: All contributions welcome!

The codebase is a well-structured TypeScript with 70%+ test coverage. Check out the CONTRIBUTING.md for details.

Why I Built This

As a developer, I was frustrated with security tools that:

Charged money for basics
Uploaded code to remote servers
Imposed usage limits
Forced a single vendor

Security tools should be accessible to everyone.

Get Started Today

npm install -g guardscan
guardscan init
guardscan security

⭐ Star the repo

Your Feedback Matters

What features would you like to see? What security checks are missing? Drop a comment below!

Made with ❤️ by developers, for developers

ThoughtTap: I Built a VS Code Extension That Stops Me From Writing Terrible AI Prompts (and it's kinda working)

Nauman Tanwir — Mon, 29 Sep 2025 21:01:14 +0000

Launching on Cursor & Windsurf next week, Product Hunt in 2-3 weeks — would love your feedback before then!

TL;DR

🧠 What: VS Code extension that makes AI prompts context-aware
🎯 Why: Stop wasting time explaining your tech stack to AI tools
⚡ How: Analyzes your project automatically, optimizes prompts locally
💰 Cost: Free tier forever, $6.99/month for Pro features
🚀 Status: Live on VS Code, launching on Cursor/Windsurf next week, Product Hunt in 2-3 weeks
🙏 Need: Your feedback before official launches

Try it:

VS Code: VS Code Marketplace
Cursor/Windsurf: Coming next week via OpenVSX Registry
Check out the website for more information - ThoughtTap

The Problem That Wouldn't Leave Me Alone

You know that moment when you copy-paste code into ChatGPT with "fix this bug" and get back a generic solution that completely ignores your TypeScript/React/AWS stack? Yeah, me too. Every. Single. Day.

I'd spend 10 minutes explaining context:

"Actually, I'm using React 18 with TypeScript"
"This is a microservices architecture"
"We're deploying to AWS Lambda"
"We use Prisma for database queries."

Then, finally, get a useful response. Rinse and repeat 20 times a day.

There had to be a better way.

The "Aha!" Moment

The problem wasn't the AI — it was the context gap. AI tools don't know:

What language/framework are you using
Your project architecture
Your deployment environment
Your testing setup

They're flying blind because we give them nothing to work with.

Enter ThoughtTap

I built a VS Code extension that automatically analyzes your project and transforms basic prompts into context-aware requests.

Before:

Help me optimize this database query

After ThoughtTap:

Help me optimize this PostgreSQL query in a Node.js TypeScript 

application using Prisma ORM. The query runs in a microservices architecture deployed on AWS Lambda with connection pooling

constraints. The current query execution time is 2.3s and needs to be 

under 500ms. Consider database indexes, query structure, and Prisma-

specific optimizations.

The AI now has everything it needs to give me a useful answer on the first try.

How It Works (The Technical Bits)

ThoughtTap hooks into VS Code's extension API and analyzes:

Language Detection: File extensions + syntax patterns
Framework Recognition: Parses package.json, requirements.txt, pom.xml
Project Structure: Workspace layout, dependencies, architecture patterns
Code Context: Selected code blocks for specific optimization

All processing happens locally in VS Code — your code never leaves your machine.

interface ProjectContext {
  language: string;                    // 'typescript'
  frameworks: string[];                // ['React', 'Next.js']
  projectType: 'web' | 'backend' | ...; // 'web'
  dependencies: string[];              // ['prisma', 'aws-sdk']
  currentFile?: FileContext;
}

The optimization engine uses:

Rule-based processing (<100ms) for grammar, structure, clarity
Template matching for common patterns (debugging, code review, architecture)
AI provider integration (Pro) for advanced optimization

Real-World Impact

Here's what early testers are reporting (mostly VS Code users, gathering Cursor/Windsurf feedback next week):

⏱️ Time saved: 10-15 minutes per complex AI interaction
🎯 First-response quality: 3-4x improvement in useful answers
🔄 Back-and-forth reduction: From 5+ clarifications to 1-2
💰 API cost savings: Fewer tokens wasted on bad prompts

Why I'm Building This Publicly

I'm taking the bootstrap approach — no VC funding, 100% user-focused. This means:

You shape the product through feedback
Your needs drive the roadmap
Privacy-first — local processing, your AI keys
Fair pricing — $6.99/month Pro (30% less than competitors)

Multi-Editor From Day One

I'm launching on VS Code first, then expanding to Cursor and Windsurf next week via the OpenVSX Registry. Why? Because developers are moving to these AI-powered editors, ThoughtTap should work wherever you code.

If you're using Cursor or Windsurf, your feedback is especially valuable — let me know what works differently in your editor!

Free vs Pro: What You Get

Free Tier (Always Free)

✅ Core optimization engine
✅ 10 developer templates
✅ Context analysis (language, frameworks)
✅ Up to 5 custom rules
✅ Right-click optimization

Pro Tier ($6.99/month)

✨ Advanced DevOps & architecture rules
✨ Cloud deployment optimization (AWS/Azure/GCP)
✨ 25+ specialized templates
✨ AI provider integration (OpenAI/Anthropic/Google)
✨ Up to 20 custom rules
✨ Settings sync + 90-day history

The Bigger Vision

ThoughtTap starts with developers because that's where the pain is sharpest. But the vision extends beyond code.

Our Strategic Roadmap (see full roadmap on GitHub):

Phase 1 (Months 1-12): "Tap into AI-enhanced development intelligence"

Focus on VS Code, Cursor, and Windsurf with deep developer workflow integration

Phase 2 (Year 2+): Web app + Chrome extension for universal use

Imagine the same context-aware optimization for:

Business prompts (reports, analysis, strategy)
Creative work (writing, design briefs)
Academic research (citations, analysis)

But first, I need to nail the developer experience. That's where you come in.

I Need Your Feedback

Before the Product Hunt launch next week, I'm looking for:

Technical Feedback:

Does the context analysis catch your project setup correctly?
Are the optimization rules actually useful?
What frameworks/languages should I prioritize?
Performance issues? (It should be <100ms for most operations)

UX Feedback:

Is the workflow intuitive?
What's confusing or unclear?
What features are you missing?
Where does it feel clunky?

Strategic Feedback:

Would you actually pay $6.99/month for the Pro features?
What would make this a "must-have" tool?
What's missing that would prevent you from using it daily?

Try It Now (Pre-Launch Access)

VS Code Users

ThoughtTap is live on the VS Code Marketplace:

Open VS Code
Search "ThoughtTap" in Extensions
Install
Select any text → Right-click → "ThoughtTap: Optimize"

Or use the keyboard shortcut: Ctrl+Shift+O (Cmd+Shift+O on Mac)

Installation: VS Code Marketplace

Cursor & Windsurf Users

Coming Next Week! ThoughtTap will be available on:

OpenVSX Registry (for both Cursor and Windsurf)
Cursor Marketplace (OpenVSX-powered)
Windsurf Marketplace (marketplace.windsurf.com)

I'm publishing to OpenVSX next week to reach Cursor and Windsurf users. If you're using these editors, drop a comment and I'll notify you when it's live!

The Ask

If you try ThoughtTap:

⭐ Drop a comment with your honest feedback (brutal honesty welcome!)
🐛 Report bugs via GitHub Issues
💡 Share ideas for features you'd actually use (GitHub Issues or contact page)
🚀 Spread the word if you find it useful

Stay connected:

🐛 Report Bugs: GitHub Issues
💬 Get in Touch: thoughttap.com/contact
🗺️ View Roadmap: GitHub Roadmap
⭐ Star on GitHub: github.com/ntanwir10/ThoughtTap

What's Next

This Week:

Polish based on your feedback
Fix any critical bugs
Add most-requested features

Next Week:

Publish to OpenVSX Registry
Launch on Cursor & Windsurf marketplaces
Support multi-editor user base

Weeks 2-3:

Product Hunt launch
Official marketing push
Community building campaign

Month 2-3:

Advanced AI provider integrations
Custom template builder
Team collaboration features

A Note on Sustainability

I'm building ThoughtTap as a sustainable business, not a VC-funded rocket ship. This means:

No pressure to pivot away from what users need
Long-term thinking over quick exits
Fair pricing that reflects actual value
User privacy over data monetization

If this resonates with you, give ThoughtTap a shot and let me know what you think.

Discussion

I'm curious about your experiences:

What's your biggest frustration with AI coding assistants?
How much time do you spend clarifying context to AI tools daily?
Would you trust a VS Code extension with your project analysis?
What would make you choose ThoughtTap over just learning better prompting?
Are you using Cursor or Windsurf? What features would you need most?

Let's discuss in the comments! 👇

Building an AI-Powered Anomaly Detection System with Redis 8: Beyond Traditional Caching

Nauman Tanwir — Sun, 10 Aug 2025 21:31:25 +0000

Building an AI-Powered Anomaly Detection System with Redis 8: Beyond Traditional Caching

This is a submission for the Redis AI Challenge: Beyond the Cache.

What I Built

I've built a production-ready AI Anomaly Detection System that transforms Redis 8 from a simple cache into a powerful real-time data processing and machine learning platform. This system monitors microservices, detects anomalies using AI, and provides instant alerts - all powered by Redis 8's advanced features.

🚀 Key Features

Real-time Anomaly Detection: Uses Isolation Forest ML algorithm to detect system anomalies
Multi-Service Monitoring: Tracks API endpoints, status codes, response times, and business metrics
Redis Streams + Pub/Sub: Real-time data ingestion and instant alert broadcasting
Count-Min Sketches: Memory-efficient probabilistic data structures for high-frequency metrics
RedisGears Integration: Server-side data aggregation and processing
Production-Ready SDKs: Python and JavaScript clients for easy integration
Modern Dashboard: Real-time visualization with WebSocket updates

Demo

ntanwir10 / AI-Anamoly-Detector

A highly efficient, real-time anomaly detection system for distributed microservices architecture that leverages Redis's advanced probabilistic data structures (RedisBloom) for memory-efficient data collection and RedisGears for in-database processing. An AI model analyzes data patterns to identify and predict system failures before they cascade.

AI-Driven Distributed System Anomaly Detection

A production-ready, real-time anomaly detection system for distributed microservices architecture that leverages Redis's advanced probabilistic data structures (RedisBloom) for memory-efficient data collection and RedisGears for in-database processing. An AI model analyzes data patterns to identify and predict system failures before they cascade.

🏆 Built for the Redis AI Challenge - This project showcases Redis as a high-performance, multi-model engine for complex data processing and analysis pipelines, demonstrating Redis capabilities far beyond traditional caching.

Competing in the "Beyond the Cache" challenge prompt, demonstrating how Redis can do much more than traditional caching by serving as a primary database, full-text search engine, real-time streams processor, and pub/sub messaging system.

This system is designed for real-world deployment and includes comprehensive integration options, client SDKs, and enterprise-grade features for monitoring distributed systems at scale.

📑 Table of Contents

View on GitHub

The system is fully containerized and can be deployed with a single command:

docker-compose up -d

📱 Dashboard Screenshots

The dashboard provides real-time insights into:

🔗 Quick Start

# Clone the repository
git clone https://github.com/ntanwir10/AI-Anamoly-Detector
cd ai-anomaly-detector

# Start all services
docker-compose up -d

# Access the dashboard
open http://localhost:3001

# Send test metrics
curl -X POST http://localhost:4000/metrics \
  -H "Content-Type: application/json" \
  -d '{"service": "test", "endpoint": "GET:/api/test", "status_code": 200}'

🏗️ How This Works

Architecture Overview

The system is composed of six main components with real data integration capabilities:

Real Data Sources + Demo Simulation: Production data sources (APM, business metrics, logs) + simulated microservices for testing
Enhanced Data Collector: Production-ready collector with real data APIs, business metrics, and log processing
Redis Core: The central engine, running with the RedisBloom and RedisGears modules. It ingests real data, aggregates it, and stores the system's "fingerprint."
AI Anomaly Service: A Python service that reads the fingerprint data from Redis, trains an anomaly detection model, and identifies outlier patterns in real data.
Dashboard UI: A React frontend with real-time WebSocket updates showing live system health and anomalies
Real Data Integration Layer: APM providers, business applications, infrastructure monitoring, and enterprise systems

Data Flow Architecture

Enhanced Data Flow Diagram

How It Works

Real Data Processing

Production Data Ingestion: Real applications send metrics via enhanced APIs every few seconds
Enhanced Data Collection: The Enhanced Data Collector processes multiple data types and sends commands to Redis:
- CF.ADD service-calls service:endpoint (Real service interactions)
- CMS.INCRBY api-frequency endpoint 1 (Real API usage patterns)
- CMS.INCRBY business-metrics metric_name 1 (Business KPIs)
- XADD detailed-metrics * data <real_metrics> (Full-fidelity production data)
In-Database Aggregation: Every 5 seconds, RedisGears creates system fingerprints from real data
AI Analysis: ML models learn from real production patterns and detect anomalies in live data
Real-time Alerting: Production alerts with business context and severity assessment
Visualization: Dashboard shows real production metrics and anomalies

Demo Mode (For Testing)

Traffic Generation: Microservice A makes GET /api/v1/users calls to Microservice B every 2 seconds
Data Collection: The Data Collector observes demo traffic and sends commands to Redis
In-Database Aggregation: RedisGears creates system fingerprints every 5 seconds
AI Analysis: ML models detect anomalies in simulated traffic patterns
Real-time Alerting: Demo alerts are published to Redis Pub/Sub for testing
Visualization: Dashboard displays real-time demo data and anomalies

How I Used Redis 8

🎯 Beyond Traditional Caching

This project demonstrates Redis 8's capabilities far beyond simple key-value storage:

1. Redis Streams for Real-Time Data Processing

# Continuous data ingestion from multiple sources
def read_stream_blocking(r: redis.Redis, last_id: str):
    resp = r.xread({STREAM_KEY: last_id}, count=1, block=10_000)
    if not resp:
        return last_id, None
    _, entries = resp[0]
    entry_id, fields = entries[0]
    return entry_id, fields

Redis Streams act as a distributed log, allowing the AI service to process metrics in real-time without losing data. This is crucial for anomaly detection where timing is everything.

2. Count-Min Sketches for Memory-Efficient Analytics

# Initialize probabilistic data structures
redis_cmd("CMS.INITBYDIM", "endpoint-frequency", 100000, 10)
redis_cmd("CMS.INITBYDIM", "status-codes", 100000, 10)

# Aggregate high-frequency metrics efficiently
def read_count_min_sketch(key: str, items: List[str]) -> List[int]:
    res = redis_cmd("CMS.QUERY", key, *items)
    return [int(x) for x in res]

Instead of storing every single API call (which could be millions per day), Count-Min Sketches provide approximate counts with guaranteed error bounds. This allows monitoring of high-frequency metrics without memory explosion.

3. Pub/Sub for Instant Alert Broadcasting

# Publish anomaly alerts to all subscribers
if pred[0] == -1:  # Anomaly detected
    msg = "Anomaly detected: Outlier fingerprint observed."
    r.publish(PUBSUB_CHANNEL, msg)

When the AI model detects an anomaly, Redis Pub/Sub instantly broadcasts the alert to all dashboard clients and monitoring systems, ensuring zero-latency notification.

4. RedisGears for Server-Side Processing

# Server-side aggregation every 5 seconds
def aggregate_tick():
    vec = build_fingerprint()
    write_to_stream(vec)
    log("Aggregation completed")

RedisGears runs Python code directly in Redis, performing real-time aggregation of metrics into system "fingerprints" that the AI model can analyze. This eliminates the need for external aggregation services.

5. Hybrid Data Model

The system combines multiple Redis data structures:

Streams: Time-series data ingestion
Count-Min Sketches: Probabilistic counters
Pub/Sub: Real-time messaging
Strings: Configuration and metadata
Hashes: Service-specific data

🔬 AI Integration Architecture

Machine Learning Pipeline

# Training phase with Redis Streams
training_vectors: List[List[float]] = []
while len(training_vectors) < training_target:
    last_id, fields = read_stream_blocking(r, last_id)
    vec = parse_vector(fields)
    if vec:
        training_vectors.append(vec)

# Train Isolation Forest model
X_train = np.array(training_vectors)
model = IsolationForest(contamination="auto", random_state=42)
model.fit(X_train)

# Real-time anomaly detection
while True:
    vec = parse_vector(fields)
    X_new = np.array([vec])
    pred = model.predict(X_new)  # 1=normal, -1=anomaly

The AI service continuously reads from Redis Streams, trains on normal system behavior, and then monitors for deviations in real-time.

📊 Real-World Use Cases

E-Commerce Platform Monitoring

// Monitor checkout flow anomalies
const anomalyClient = new AnomalyClient('https://anomaly-detector.company.com', 'api-key');

// Track payment processing
await anomalyClient.sendMetric({
  service: 'payment-processor',
  endpoint: 'POST:/api/payments',
  metrics: {
    response_time: 245,
    status_code: 200,
    amount: 99.99
  }
});

// Business metrics
await anomalyClient.sendBusinessMetric('daily_revenue', 45000, [40000, 60000]);

Financial Services

# Monitor transaction processing
client.send_metric({
    'service': 'transaction-engine',
    'endpoint': 'POST:/api/transactions',
    'metrics': {
        'processing_time': 150,
        'amount': 5000.00,
        'risk_score': 0.02
    }
})

SaaS Platform Health

# Track feature usage patterns
client.send_business_metric('feature_adoption', 0.85, expected_range=[0.7, 0.95])
client.send_metric({
    'service': 'user-service',
    'endpoint': 'GET:/api/users',
    'metrics': {'response_time': 45, 'cache_hit_rate': 0.92}
})

🚀 Performance Characteristics

Throughput: 10,000+ metrics/second per collector instance
Latency: <50ms for metric ingestion, <1s for anomaly detection
Memory Efficiency: ~1GB for 1M service interactions using Count-Min Sketches
Scalability: Horizontal scaling with Redis clustering support

🔧 Production Deployment

The system includes production-ready configurations:

# High Availability Setup
services:
  - Redis Cluster (3 nodes) - Data persistence & processing
  - Data Collector (2+ replicas) - Load balanced ingestion
  - AI Service (1 replica) - Model training & detection
  - Dashboard (2+ replicas) - User interface & API

💡 Key Innovations

Probabilistic Monitoring: Count-Min Sketches enable monitoring of high-frequency events without memory explosion
Real-Time AI: Continuous model training and anomaly detection using Redis Streams
Zero-Latency Alerts: Pub/Sub ensures instant notification of issues
Server-Side Processing: RedisGears eliminates external aggregation overhead
Unified Data Platform: Single Redis instance handles all aspects of monitoring

🌟 Why This Matters

Traditional monitoring systems often suffer from:

Alert Fatigue: Too many false positives
Data Silos: Separate systems for logs, metrics, and alerts
High Latency: Batch processing delays
Memory Explosion: Storing every single event

This Redis-powered solution addresses all these issues by:

Using AI to reduce false positives by 80%
Unifying all data in Redis with appropriate data structures
Providing real-time processing with Redis Streams
Using probabilistic structures for memory efficiency

🔮 Future Enhancements

The architecture is designed for extensibility:

Multi-Model Support: Different ML algorithms for different metric types
Custom Aggregations: User-defined RedisGears scripts
Regional Deployment: Edge instances for global monitoring
Advanced Analytics: Time-series analysis and forecasting

📚 Getting Started

The project includes comprehensive documentation and examples:

🎉 Conclusion

This project demonstrates how Redis 8 can be transformed from a simple cache into a powerful real-time data processing and AI platform. By leveraging Redis Streams, Count-Min Sketches, Pub/Sub, and RedisGears, we've built a production-ready anomaly detection system that scales from startups to enterprises.

The key insight is that Redis isn't just for caching anymore - it's a complete data platform that can handle real-time streaming, probabilistic analytics, machine learning workflows, and instant messaging, all while maintaining the performance and reliability that made Redis famous.

Redis 8: Beyond the Cache, Into the Future of Real-Time AI.

Real-Time AI Dungeon Master: Multiplayer Storytelling with Redis 8 (Streams, Pub/Sub, RedisJSON)

Nauman Tanwir — Sat, 09 Aug 2025 19:33:01 +0000

This is a submission for the Redis AI Challenge: Real-Time AI Innovators

What I Built

Real-Time AI Dungeon Master is a multiplayer, AI-driven storytelling game that uses Redis as its real-time data layer to synchronize sessions, broadcast narrative updates, and persist game history.

AI Dungeon Master: Narrative powered by OpenAI GPT with contextual prompts
Multiplayer in real time: Players join a shared session and collaborate via WebSocket (Socket.IO)
Redis-first architecture:
- Sessions: HSET game:{sessionId}:state (status, created_at, last_activity)
- Event log: XADD game:{sessionId}:events (immutable history and replay)
- Active players: SADD game:{sessionId}:players
- Broadcasts: PUBLISH game:{sessionId}:updates → Socket.IO game:update
- Semantic lore: JSON.SET lore:{id} (embeddings + metadata)
Production-friendly: Rate limiting, error handling, environment validation, health checks, graceful shutdown
Full stack: Node.js/TypeScript backend, React + Tailwind frontend, Dockerized with nginx proxy

Repository: github.com/ntanwir10/realtime_ai_dungeon_master

ntanwir10 / realtime_ai_dungeon_master

AI-powered collaborative storytelling through real-time multiplayer adventures! Built entirely around Redis as the high-performance real-time data layer, this project pushes the boundaries of interactive AI gaming.

🐍 Real-Time AI Dungeon Master - Redis AI Challenge Submission

🚀 AI-powered collaborative storytelling through real-time multiplayer adventures! Built entirely around Redis as the high-performance real-time data layer, this project pushes the boundaries of interactive AI gaming.

Real-Time AI Dungeon Master - The ultimate AI-powered multiplayer game, leveraging Redis for seamless real-time state management and dynamic storytelling.

Built for the Redis AI Challenge 🏆

Competing in the "Real-Time AI Innovators" challenge prompt, demonstrating how Redis accelerates the future of AI through high-impact use cases like real-time feature streaming, semantic caching, and advanced state management.

📋 Table of Contents

View on GitHub

Demo

If this isn’t live at the moment, you can run it locally in minutes.

Full walk‑through demo (screen recording): Shows creating a session, joining, sending commands, and receiving AI narratives in real time.

Quick start with Docker:

git clone https://github.com/ntanwir10/realtime_ai_dungeon_master
cd realtime_ai_dungeon_master
cp backend/.env.example backend/.env   # add your OpenAI API key
docker-compose up --build
# Frontend: http://localhost:5173
# Backend:  http://localhost:3001

Manual development setup:

# Redis JSON
docker run -d -p 6379:6379 redislabs/rejson:latest

# Backend
cd backend && npm install && npm run dev

# Frontend
cd ../frontend && npm install && npm run dev

Screenshots

Landing Page, Session Details and Create Session

In‑Game View: Story Log after a command and Multiplayer Gameplay

Redis CLI: Sessions, State, Events, Players
![Redis CLI views]

List all keys (overview)

List all sessions

Showing multiple user sessions’ state

Show recent events for that session (Streams)

Show active players in that session (Sets)

Live Pub/Sub Screen recording

Pub/Sub live updates (Redis PSUBSCRIBE + client command → narrative broadcast):

How I Used Redis 8

This project treats Redis as the system-of-record and real-time backbone. It uses Redis 8–8-compatible primitives plus RedisJSON for AI-centric data.

Real-time event streaming (Streams)
- XADD game:{sessionId}:events captures every player action as an immutable event
- XRANGE builds AI context and enables replay/debugging
Low-latency state access (Hashes)
- HSET game:{sessionId}:state stores session status and timestamps for fast reads (HGETALL, HGET)
Presence and discovery (Sets + Keys)
- SADD game:{sessionId}:players tracks active players; SCARD for presence count
- KEYS game:*:state supports session discovery for the session browser
Broadcast updates (Pub/Sub)
- Backend publishes narrative updates to game:{sessionId}:updates
- A Redis subscriber relays messages to Socket.IO game:update for all connected clients
Semantic lore with JSON and embeddings (RedisJSON)
- Lore entries are stored as JSON: lore:{id} with { id, type, title, content, embedding, tags, created_at, updated_at }
- Embeddings are generated with OpenAI and stored directly in Redis JSON
- Semantic similarity is computed in the app layer via cosine similarity, enabling contextual prompts
- Type and tag indexing via Sets: lore:type:{type}, lore:tag:{tag}
- Future enhancement: swap app-layer similarity for Redis Stack vector indexes for server-side vector search

Why Redis 8 for AI apps:

Streams + Pub/Sub deliver real-time narrative fan-out with minimal latency
Hashes/Sets keep presence and session state O(1)
RedisJSON stores rich, evolving AI knowledge artifacts (lore) adjacent to fast operational data
The combination forms a semantic cache that reduces LLM prompt size and calls by grounding responses in structured, retrievable context

Team: Solo project.

Thanks for reading! If you try it, I’d love to hear your feedback. Repo: github.com/ntanwir10/realtime_ai_dungeon_master

By submitting this entry, you agree to receive communications from Redis regarding products, services, events, and special offers. You can unsubscribe at any time. Your information will be handled in accordance with Redis's Privacy Policy.

CodeSage - MCP-First Code Discovery

Nauman Tanwir — Sun, 27 Jul 2025 16:01:36 +0000

Building CodeSage: A MCP-First Code Discovery Platform

This is a submission for the Algolia MCP Server Challenge

What I Built

CodeSage is an AI-powered code discovery platform built entirely around the Model Context Protocol (MCP). It transforms GitHub repositories into AI-searchable knowledge bases, enabling natural language exploration of codebases through Claude Desktop and other MCP-compatible AI clients.

Demo

GitHub Repository: CodeSage MCP-First Code Discovery

ntanwir10 / codesage-algolia-challenge

AI-powered code discovery through natural language - Built entirely around the Model Context Protocol (MCP) for seamless integration with Claude Desktop and other AI clients

CodeSage - MCP-First Code Discovery

🚀 AI-powered code discovery through natural language - Built entirely around the Model Context Protocol (MCP) for seamless integration with Claude Desktop and other AI clients.

CodeSage - MCP-First Code Discovery - The only code discovery tool built entirely around the Model Context Protocol for seamless AI integration.

Built for the Algolia MCP Server Challenge 🏆

Competing in the Backend Data Optimization and Ultimate User Experience categories with our innovative MCP-first approach to code discovery.

🎯 What is CodeSage?

CodeSage - MCP-First Code Discovery transforms GitHub repositories into AI-searchable knowledge bases through the Model Context Protocol. Submit a repository URL, and within minutes your AI assistant can discover functions, understand architecture, and answer complex questions about the codebase through natural language - all via MCP integration.

🎯 Final User Experience

1. User submits: github.com/facebook/react
2. System processes: GitHub → Parser → Algolia
3. User opens

…

View on GitHub

Key Innovation: MCP-First Architecture

CodeSage is the only code discovery tool built entirely around MCP standards. Unlike traditional code search tools that require direct API integration, CodeSage leverages the Model Context Protocol to provide seamless AI integration, eliminating the need for direct AI API calls.

📊 Complete System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CODESAGE ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌─────────────┐ │
│  │   Frontend  │───▶│   Backend    │───▶│   Algolia   │    │   GitHub    │ │
│  │   (Simple)  │    │ (Processing) │    │  (Search)   │◀───│     API     │ │
│  └─────────────┘    └──────────────┘    └─────────────┘    └─────────────┘ │
│                              │                                             │
│                              ▼                                             │
│                     ┌──────────────┐    ┌─────────────┐                   │
│                     │     MCP      │───▶│   Claude    │                   │
│                     │   Protocol   │    │  Desktop    │                   │
│                     └──────────────┘    └─────────────┘                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Key Architecture Flows:

Repository Management: Frontend ↔ Backend
Code Discovery: Claude Desktop ↔ MCP ↔ Backend ↔ Algolia
No Direct Integration: Frontend never talks to Algolia or MCP

🔄 Processing Pipeline

1. Repository Submission Flow

User Input → Frontend → POST /repositories/ → Backend
    ↓
Database Record (status: pending)
    ↓
Background Processing Triggered
    ↓
GitHub API Integration
    ↓
File Parsing & Analysis
    ↓
Algolia Indexing
    ↓
Status Update (status: completed)

2. Code Discovery Flow

Claude Desktop User Query
    ↓
MCP Protocol Call
    ↓
POST /api/v1/ai/mcp/tools/call
    ↓
MCP Tool Execution
    ↓
Algolia Search Query
    ↓
Search Results
    ↓
Formatted Response
    ↓
Claude Desktop Display

Core Features:

Repository Processing: Automatic ingestion and parsing of GitHub repositories
Algolia-Powered Search: Fast, semantic code search with intelligent indexing
MCP Tools: Natural language code discovery through Claude Desktop
Real-time Processing: Live status updates and WebSocket integration
Multi-language Support: Parses functions, classes, and imports across languages

How I Utilized the Algolia MCP Server

1. MCP-First Architecture Design

CodeSage is built entirely around the Model Context Protocol, making it unique among code discovery tools. The architecture follows this flow:

User Query → Claude Desktop → MCP Protocol → CodeSage Backend → Algolia Search → Formatted Results

2. Algolia Integration for Code Search

I implemented a comprehensive Algolia service that:

Indexes Code Entities: Functions, classes, variables, and imports are parsed and indexed with semantic metadata
Optimized Search Settings: Configured searchable attributes, faceting, and custom ranking for code-specific relevance
Multi-language Support: Handles Python, JavaScript, TypeScript, and other languages
Repository Isolation: Each repository gets its own search context

3. MCP Tools Implementation

I created five core MCP tools that leverage Algolia's search capabilities:

search_code: Natural language code search across repositories
analyze_repository: Repository overview and architectural insights
explore_functions: Function discovery and relationship mapping
explain_code: Detailed code explanations and documentation
find_patterns: Pattern detection for security, performance, and architecture

4. Real-world Usage Example

# User submits repository
POST /api/v1/repositories/
{
  "url": "https://github.com/facebook/react"
}

# User asks Claude Desktop
"Show me React's rendering lifecycle functions"

# Claude uses MCP tool
POST /api/v1/ai/mcp/tools/call
{
  "tool_name": "search_code",
  "arguments": {
    "query": "rendering lifecycle",
    "repository": "react"
  }
}

# Algolia returns relevant functions
# Claude provides AI-powered analysis

5. MCP Tools Available

search_code - Natural language code search across repositories
analyze_repository - Repository overview and architectural insights
explore_functions - Function discovery and relationship mapping
explain_code - Detailed code explanations and documentation
find_patterns - Pattern detection for security, performance, architecture

6. Technical Implementation

🏗 System Components

Backend (FastAPI)

Location: backend/app/

Core Services:

repository_service.py - Repository CRUD and processing logic
mcp_server.py - MCP protocol implementation
ai_service.py - MCP tools implementation
algolia_service.py - Search indexing and querying
security_service.py - Rate limiting and validation

Database Models:

Repository - Repository metadata and status
CodeFile - Individual file records
CodeEntity - Functions, classes, imports extracted from files

API Endpoints:

# Repository Management
GET    /api/v1/repositories/        # List repositories
POST   /api/v1/repositories/        # Create repository  
GET    /api/v1/repositories/{id}    # Get repository
DELETE /api/v1/repositories/{id}    # Delete repository

# MCP Protocol
GET    /api/v1/ai/mcp/capabilities     # MCP server capabilities
GET    /api/v1/ai/mcp/tools           # List MCP tools
POST   /api/v1/ai/mcp/tools/call      # Execute MCP tool
GET    /api/v1/ai/mcp/resources/read  # Read MCP resource

Frontend (React + TypeScript)

Location: frontend/src/

Purpose: Simple repository management interface

Repository submission form
Repository list with status
Basic CRUD operations
No complex search UI - AI discovery happens through Claude Desktop

Key Components:

Repository form with GitHub URL validation
Real-time status tracking via WebSocket
Modern UI with TailwindCSS

Tech Stack

Backend Stack:

FastAPI for MCP server implementation
SQLAlchemy for data persistence
Algolia for search indexing and querying
WebSocket for real-time status updates

Frontend Stack:

React 18 with TypeScript
TailwindCSS for modern UI
Real-time status tracking

MCP Integration:

Custom MCP server implementation
Tool-based architecture for extensibility
Resource-based data access patterns

Key Takeaways

Development Process

Building CodeSage taught me several valuable lessons about MCP-first architecture:

MCP Standards Matter: Building around MCP from the ground up creates a more flexible and extensible system than retrofitting existing tools
Tool Design is Critical: Well-designed MCP tools can provide powerful AI capabilities without requiring direct AI API integration
Search Integration is Key: Algolia's semantic search capabilities perfectly complement MCP's natural language interface

Challenges Faced

MCP Protocol Complexity: Understanding and implementing the Model Context Protocol required a deep dive into the specification
Search Optimization: Configuring Algolia for code-specific search patterns required extensive testing and tuning
Real-time Processing: Implementing background processing with status updates required careful WebSocket integration
Error Handling: MCP tools need robust error handling to provide meaningful feedback to AI clients

What I Learned

MCP-First Design: Building around MCP standards from the start creates more AI-friendly applications
Search Architecture: Algolia's faceting and filtering capabilities are perfect for code discovery
Tool Abstraction: Well-designed MCP tools can abstract complex operations into simple natural language interfaces
Performance Optimization: Code search requires careful indexing strategies and query optimization

Technical Innovations

MCP-First Code Discovery: The only code discovery tool built entirely around MCP standards
Algolia-MCP Integration: Seamless integration between Algolia's search capabilities and MCP's tool system
Natural Language Code Exploration: Users can ask complex questions about codebases through Claude Desktop
Repository Processing Pipeline: Automated ingestion, parsing, and indexing of GitHub repositories

Future Possibilities

CodeSage demonstrates the potential for MCP-first applications in various domains:

Documentation Discovery: Similar approach for technical documentation
API Exploration: Natural language API discovery and testing
Security Analysis: AI-powered security pattern detection
Code Review: Automated code review through MCP tools

The combination of Algolia's powerful search capabilities with MCP's natural language interface opens up exciting possibilities for AI-powered development tools.

🚀 Impact

CodeSage represents a fundamental shift in how developers interact with codebases. As the first MCP-first code discovery platform, it demonstrates:

AI-Native Design: Building around MCP standards creates more powerful AI integration
Natural Language Future: Developers can ask complex questions about codebases in plain English
Search + AI Synergy: Algolia's semantic search combined with MCP's natural language interface

This project has broader implications for the AI tool ecosystem, showing how to build applications that work seamlessly with Claude Desktop and other MCP clients. The architecture can be applied to documentation discovery, API exploration, security analysis, and knowledge management.

CodeSage proves that MCP-first applications can revolutionize how we interact with complex data through natural language, opening new possibilities for AI-powered development tools.

Thanks for participating! 🚀

This project represents a new paradigm in AI-powered development tools, one where the Model Context Protocol enables seamless integration between powerful search engines, such as Algolia, and AI assistants, like Claude Desktop.

Deploying FastAPI to AWS: Part 3 - Going Serverless with Lambda

Nauman Tanwir — Sun, 13 Jul 2025 18:22:06 +0000

This is Part 3 of our FastAPI deployment series. We've covered EC2 and ECS Fargate - now let's explore the serverless approach.

After deploying my FastAPI journal API using EC2 and ECS Fargate, I started working on some side projects. The problem? Even the smallest ECS setup was costing me $30-50/month per project, and most of my side projects get maybe 100 requests per day.

That's when I discovered Lambda could run the same FastAPI application for literally $1-2 per month. Here's how serverless changed my approach to deploying personal projects.

When Serverless Makes Sense

Lambda isn't always the answer, but it's perfect when:

Variable traffic: Some days 10 requests, some days 1000
Cost is a concern: You want to pay only for what you use
Minimal maintenance: You don't want to manage any infrastructure
Quick experiments: You want to deploy and test ideas fast

For my journal API side project, Lambda was perfect because I'm the only user most days, but occasionally I share it with friends for feedback.

The Serverless Architecture

Here's what we're building:

Internet → API Gateway → Lambda Functions → RDS Proxy → RDS PostgreSQL
                                    ↓
                            CloudWatch Logs (automatic)

This setup gives us:

Pay-per-request pricing
Automatic scaling (0 to thousands of requests)
No server management
Built-in monitoring

Step 1: Adapting FastAPI for Lambda

Lambda doesn't run web servers like uvicorn. Instead, it processes events. We need an adapter to make FastAPI work with Lambda events.

Install Mangum

pip install mangum

Modify Your FastAPI App

Create a new file lambda_handler.py:

from mangum import Mangum
from app.main import app

# Disable lifespan events for Lambda
app.router.lifespan_context = None

# Create the Lambda handler
handler = Mangum(app, lifespan="off")

Update Your FastAPI App

Make some Lambda-friendly changes to your main app:

# In app/main.py
from fastapi import FastAPI
from contextlib import asynccontextmanager
import os

# Check if running in Lambda
IS_LAMBDA = os.environ.get('AWS_LAMBDA_FUNCTION_NAME') is not None

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    if not IS_LAMBDA:
        # Only run startup tasks when not in Lambda
        print("Starting up...")
    yield
    # Shutdown
    if not IS_LAMBDA:
        print("Shutting down...")

# Create app with conditional lifespan
if IS_LAMBDA:
    app = FastAPI(title="Journal API")
else:
    app = FastAPI(title="Journal API", lifespan=lifespan)

# Your existing routes...

Handle Database Connections

Lambda functions are stateless, so we need to handle database connections carefully:

# In your database connection file
import os
from sqlalchemy import create_engine
from sqlalchemy.pool import NullPool

def get_database_url():
    if os.environ.get('AWS_LAMBDA_FUNCTION_NAME'):
        # Use RDS Proxy for Lambda
        return f"postgresql://{user}:{password}@{rds_proxy_endpoint}:5432/{database}"
    else:
        # Direct connection for local development
        return f"postgresql://{user}:{password}@{rds_endpoint}:5432/{database}"

# Create engine with appropriate pooling
if os.environ.get('AWS_LAMBDA_FUNCTION_NAME'):
    # No connection pooling for Lambda
    engine = create_engine(get_database_url(), poolclass=NullPool)
else:
    # Normal pooling for non-Lambda environments
    engine = create_engine(get_database_url())

Step 2: Set Up RDS Proxy

Lambda functions can overwhelm your database with connections. RDS Proxy solves this by managing connection pooling.

Create RDS Proxy

# First, create a secret for database credentials
aws secretsmanager create-secret \
    --name journal-db-credentials \
    --description "Database credentials for journal API" \
    --secret-string '{"username":"postgres","password":"YourSecurePassword123"}'

# Create RDS Proxy
aws rds create-db-proxy \
    --db-proxy-name journal-db-proxy \
    --engine-family POSTGRESQL \
    --auth '{
        "AuthScheme": "SECRETS",
        "SecretArn": "arn:aws:secretsmanager:us-east-1:account:secret:journal-db-credentials",
        "IAMAuth": "DISABLED"
    }' \
    --role-arn arn:aws:iam::account:role/RDSProxyRole \
    --vpc-subnet-ids subnet-xxxxxxxxx subnet-yyyyyyyyy \
    --vpc-security-group-ids sg-xxxxxxxxx

# Register RDS instance with proxy
aws rds register-db-proxy-targets \
    --db-proxy-name journal-db-proxy \
    --db-instance-identifiers journal-db

Step 3: Package and Deploy with SAM

AWS SAM makes Lambda deployment much easier. Create a template.yaml:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 30
    MemorySize: 512
    Runtime: python3.11

Parameters:
  DatabaseHost:
    Type: String
    Description: RDS Proxy endpoint

Resources:
  JournalApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Handler: lambda_handler.handler
      Environment:
        Variables:
          POSTGRES_HOST: !Ref DatabaseHost
          POSTGRES_PORT: 5432
          POSTGRES_DB: journal_db
      Events:
        ApiGateway:
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: ANY
        ApiGatewayRoot:
          Type: Api
          Properties:
            Path: /
            Method: ANY
      VpcConfig:
        SecurityGroupIds:
          - sg-xxxxxxxxx
        SubnetIds:
          - subnet-xxxxxxxxx
          - subnet-yyyyyyyyy

  # IAM role for Lambda
  JournalApiRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
      Policies:
        - PolicyName: SecretsManagerAccess
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - secretsmanager:GetSecretValue
                Resource: 
                  - arn:aws:secretsmanager:*:*:secret:journal-db-credentials*

Outputs:
  ApiGatewayUrl:
    Description: "API Gateway endpoint URL"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/"

Deploy with SAM

# Build the application
sam build

# Deploy
sam deploy --guided

The guided deployment will ask for:

Stack name: journal-api-lambda
AWS Region: us-east-1
Database host: Your RDS Proxy endpoint
Confirm changes before deploy: Y

Step 4: Handle Database Migrations

Lambda functions are ephemeral, so we need a different approach for migrations. Create a separate Lambda function:

# migration_handler.py
import subprocess
import os

def handler(event, context):
    """Run Alembic migrations in Lambda"""
    try:
        # Set database URL from environment
        os.environ['DATABASE_URL'] = f"postgresql://{os.environ['POSTGRES_USER']}:{os.environ['POSTGRES_PASSWORD']}@{os.environ['POSTGRES_HOST']}:5432/{os.environ['POSTGRES_DB']}"

        # Run migrations
        result = subprocess.run(['alembic', 'upgrade', 'head'], 
                              capture_output=True, text=True)

        if result.returncode == 0:
            return {
                'statusCode': 200,
                'body': f'Migrations completed successfully: {result.stdout}'
            }
        else:
            return {
                'statusCode': 500,
                'body': f'Migration failed: {result.stderr}'
            }
    except Exception as e:
        return {
            'statusCode': 500,
            'body': f'Error running migrations: {str(e)}'
        }

Add this to your SAM template:

  MigrationFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Handler: migration_handler.handler
      Timeout: 300
      Environment:
        Variables:
          POSTGRES_HOST: !Ref DatabaseHost
          POSTGRES_PORT: 5432
          POSTGRES_DB: journal_db

Step 5: Testing and Monitoring

Test Your Lambda Function

# Get your API Gateway URL from SAM output
curl https://your-api-id.execute-api.us-east-1.amazonaws.com/Prod/health

# Test authentication
curl -X POST https://your-api-id.execute-api.us-east-1.amazonaws.com/Prod/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "testpass123"}'

Monitor Performance

Lambda automatically sends metrics to CloudWatch:

# View function metrics
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/journal-api

# View recent logs
aws logs tail /aws/lambda/journal-api-JournalApiFunction-XXXXXXXXX --follow

Step 6: Optimize for Production

Handle Cold Starts

Cold starts can add 1-3 seconds to the first request. Here are some optimizations:

# In lambda_handler.py
import json
from mangum import Mangum
from app.main import app

# Initialize outside the handler for reuse
handler = Mangum(app, lifespan="off")

# Warm-up function
def lambda_handler(event, context):
    # Handle ALB health checks
    if event.get('httpMethod') == 'GET' and event.get('path') == '/health':
        return {
            'statusCode': 200,
            'body': json.dumps({'status': 'healthy'}),
            'headers': {'Content-Type': 'application/json'}
        }

    # Handle normal requests
    return handler(event, context)

Use Provisioned Concurrency

For critical endpoints, you can eliminate cold starts:

# Add to your SAM template
  JournalApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      # ... other properties
      ProvisionedConcurrencyConfig:
        ProvisionedConcurrencyLevel: 2

Optimize Package Size

Keep your deployment package small for faster cold starts:

# Create requirements-lambda.txt with only production dependencies
pip install --target ./package -r requirements-lambda.txt

Real-World Performance and Costs

Performance Comparison

Metric	EC2	ECS Fargate	Lambda
Cold Start	N/A	30-60s	1-3s
Warm Response	50-100ms	50-100ms	50-100ms
Scaling Time	Manual	1-2 minutes	Instant
Max Concurrent	Instance limit	Task limit	1000+

Cost Comparison (for my side project)

Monthly usage: ~10,000 requests, mostly during weekdays

EC2 (t3.micro): $8.50 + RDS = ~$25/month
ECS Fargate: $15-30 + RDS = ~$35-50/month
Lambda: $0.20 + API Gateway $0.35 + RDS = ~$15/month

For low-traffic applications, Lambda is significantly cheaper.

When NOT to Use Lambda

Lambda isn't perfect for everything:

Avoid Lambda When:

Long-running processes: 15-minute execution limit
Large file processing: Memory and storage limitations
Consistent high traffic: Costs can exceed container solutions
Complex state management: Stateless nature can be limiting
Real-time applications: Cold starts affect user experience

Stick with ECS/EC2 When:

You need persistent connections (WebSockets)
Processing large files or datasets
Running background jobs longer than 15 minutes
Consistent traffic patterns make containers more cost-effective

Lessons Learned

The Good

Incredible cost savings for variable workloads
Zero infrastructure management
Automatic scaling handles any traffic spike
Built-in monitoring and logging
Fast deployment and iteration

The Challenges

Cold starts can surprise users
15-minute timeout limits some use cases
VPC configuration can be tricky
Database connection management requires RDS Proxy
Debugging is different from traditional applications

Series Wrap-Up: Which Approach Should You Choose?

After deploying the same FastAPI application three different ways, here's my recommendation framework:

Choose EC2 When:

🎓 Learning cloud fundamentals
🔧 Need specific OS configurations
💰 Predictable, steady traffic patterns
🏢 Legacy application requirements

Choose ECS Fargate When:

🚀 Building production applications
📈 Need automatic scaling and high availability
👥 Working with a team on modern DevOps practices
🛡️ Require enterprise-grade reliability

Choose Lambda When:

💸 Cost optimization is critical
⚡ Building MVPs or side projects
📊 Traffic is highly variable or unpredictable
🎯 Want zero infrastructure management

My Current Setup Strategy

For new projects, I now follow this pattern:

Start with Lambda for MVPs and experiments
Move to ECS Fargate when traffic becomes consistent
Consider EC2 only for special requirements

This approach minimizes costs during development and scales appropriately as projects grow.

What's your experience with serverless FastAPI applications? Have you tried Lambda, or are you using other serverless platforms? Share your thoughts and questions in the comments!

If this series helped you, please share it with other developers who might be facing similar deployment decisions.

This concludes our 3-part series on deploying FastAPI to AWS. Check out the other parts:

fastapi #aws #lambda #serverless #python #webdev #devops #tutorial #beginners

Deploying FastAPI to AWS: Part 2 - Containerizing with ECS Fargate

Nauman Tanwir — Sun, 13 Jul 2025 18:18:18 +0000

This is Part 2 of a 3-part series. In Part 1, we deployed FastAPI using EC2. Now let's see how containers change the game.*

After deploying my FastAPI journal API using EC2 (covered in Part 1, I started running into some operational challenges. Manual scaling, server maintenance, and the "it works on my machine" problem made me realize why so many teams are moving to containers.

In this part, we'll take the same FastAPI application and deploy it using ECS Fargate with RDS. You'll see how this approach solves many of the challenges we faced with EC2.

Why Containers Changed Everything for Me

After a few weeks of managing EC2 instances manually, I experienced:

My app crashed during a traffic spike (no auto-scaling)
A deployment broke production (environment differences)
Spending weekends doing server maintenance
Debugging issues that only happened in production

Containers solved all of these problems. Here's how.

What We're Building

Same FastAPI journal API, but now with:

Internet → Application Load Balancer → ECS Fargate Tasks → RDS PostgreSQL
                                              ↓
                                      CloudWatch Logs

This architecture gives us:

Automatic scaling based on traffic
High availability across multiple zones
Easy deployments with zero downtime
Consistent environments from dev to production

Step 1: Containerizing the FastAPI Application

First, let's create a Dockerfile for our journal API:

FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create non-root user for security
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

# Expose port
EXPOSE 8000

# Health check for ECS
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Run the application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Add a Health Check Endpoint

ECS needs a way to check if your container is healthy. Add this to your FastAPI app:

# In your main.py or create a new health.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/health")
async def health_check():
    return {"status": "healthy"}

# Add to your main app
app.include_router(router)

Test Locally

Before deploying, make sure your container works:

# Build the image
docker build -t journal-api .

# Run locally
docker run -p 8000:8000 --env-file .env journal-api

# Test it
curl http://localhost:8000/health

Step 2: Set Up AWS Infrastructure

Create ECR Repository

We need a place to store our Docker images:

# Create ECR repository
aws ecr create-repository --repository-name journal-api

# Get login token and login
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account-id.dkr.ecr.us-east-1.amazonaws.com

Push Your Image

# Tag your image
docker tag journal-api:latest your-account-id.dkr.ecr.us-east-1.amazonaws.com/journal-api:latest

# Push to ECR
docker push your-account-id.dkr.ecr.us-east-1.amazonaws.com/journal-api:latest

Create RDS Database

Instead of managing PostgreSQL ourselves, let's use RDS:

# Create DB subnet group
aws rds create-db-subnet-group \
    --db-subnet-group-name journal-db-subnet-group \
    --db-subnet-group-description "Subnet group for journal database" \
    --subnet-ids subnet-xxxxxxxxx subnet-yyyyyyyyy

# Create RDS instance
aws rds create-db-instance \
    --db-instance-identifier journal-db \
    --db-instance-class db.t3.micro \
    --engine postgres \
    --engine-version 15.4 \
    --master-username postgres \
    --master-user-password YourSecurePassword123 \
    --allocated-storage 20 \
    --vpc-security-group-ids sg-xxxxxxxxx \
    --db-subnet-group-name journal-db-subnet-group \
    --backup-retention-period 7 \
    --multi-az

Step 3: Create ECS Cluster and Task Definition

Create ECS Cluster

aws ecs create-cluster --cluster-name journal-api-cluster

Create Task Definition

This is where we define how our container should run:

{
  "family": "journal-api-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::your-account:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::your-account:role/ecsTaskRole",
  "containerDefinitions": [
    {
      "name": "journal-api",
      "image": "your-account-id.dkr.ecr.us-east-1.amazonaws.com/journal-api:latest",
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "essential": true,
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/journal-api",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "environment": [
        {
          "name": "POSTGRES_HOST",
          "value": "your-rds-endpoint.amazonaws.com"
        },
        {
          "name": "POSTGRES_PORT",
          "value": "5432"
        },
        {
          "name": "POSTGRES_DB",
          "value": "journal_db"
        }
      ],
      "secrets": [
        {
          "name": "POSTGRES_USER",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:account:secret:db-user"
        },
        {
          "name": "POSTGRES_PASSWORD",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:account:secret:db-password"
        },
        {
          "name": "SECRET_KEY",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:account:secret:jwt-secret"
        }
      ],
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      }
    }
  ]
}

aws ecs register-task-definition --cli-input-json file://task-definition.json

Step 4: Set Up Application Load Balancer

Create Application Load Balancer

# Create ALB
aws elbv2 create-load-balancer \
    --name journal-api-alb \
    --subnets subnet-xxxxxxxxx subnet-yyyyyyyyy \
    --security-groups sg-xxxxxxxxx

# Create target group
aws elbv2 create-target-group \
    --name journal-api-targets \
    --protocol HTTP \
    --port 8000 \
    --vpc-id vpc-xxxxxxxxx \
    --target-type ip \
    --health-check-path /health \
    --health-check-interval-seconds 30 \
    --healthy-threshold-count 2 \
    --unhealthy-threshold-count 3

# Create listener
aws elbv2 create-listener \
    --load-balancer-arn arn:aws:elasticloadbalancing:... \
    --protocol HTTP \
    --port 80 \
    --default-actions Type=forward,TargetGroupArn=arn:aws:elasticloadbalancing:...

Step 5: Create ECS Service with Auto Scaling

Create the Service

aws ecs create-service \
    --cluster journal-api-cluster \
    --service-name journal-api-service \
    --task-definition journal-api-task:1 \
    --desired-count 2 \
    --launch-type FARGATE \
    --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxx,subnet-yyyyyyyyy],securityGroups=[sg-xxxxxxxxx],assignPublicIp=ENABLED}" \
    --load-balancers targetGroupArn=arn:aws:elasticloadbalancing:...,containerName=journal-api,containerPort=8000

Set Up Auto Scaling

# Register scalable target
aws application-autoscaling register-scalable-target \
    --service-namespace ecs \
    --resource-id service/journal-api-cluster/journal-api-service \
    --scalable-dimension ecs:service:DesiredCount \
    --min-capacity 1 \
    --max-capacity 10

# Create scaling policy
aws application-autoscaling put-scaling-policy \
    --service-namespace ecs \
    --resource-id service/journal-api-cluster/journal-api-service \
    --scalable-dimension ecs:service:DesiredCount \
    --policy-name journal-api-scaling-policy \
    --policy-type TargetTrackingScaling \
    --target-tracking-scaling-policy-configuration '{
        "TargetValue": 70.0,
        "PredefinedMetricSpecification": {
            "PredefinedMetricType": "ECSServiceAverageCPUUtilization"
        },
        "ScaleOutCooldown": 300,
        "ScaleInCooldown": 300
    }'

Step 6: Database Migration and Testing

Run Database Migrations

You can run migrations as a one-time ECS task:

# Create migration task definition (similar to main task but with migration command)
# Then run it:
aws ecs run-task \
    --cluster journal-api-cluster \
    --task-definition journal-api-migration:1 \
    --launch-type FARGATE \
    --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxx],securityGroups=[sg-xxxxxxxxx],assignPublicIp=ENABLED}"

Test Your Deployment

# Get your load balancer DNS name
aws elbv2 describe-load-balancers --names journal-api-alb

# Test the API
curl http://your-alb-dns-name.us-east-1.elb.amazonaws.com/health
curl http://your-alb-dns-name.us-east-1.elb.amazonaws.com/docs

What I Learned: ECS vs EC2

The Good

Auto-scaling actually works: Traffic spikes don't crash your app
Zero-downtime deployments: Rolling updates happen automatically
Consistent environments: Same container runs everywhere
Better monitoring: CloudWatch integration is built-in
Less maintenance: No OS updates or server management

The Challenges

Learning curve: Understanding containers, task definitions, and ECS concepts
Debugging: Can't SSH into containers (but logs are better organized)
Cost: Slightly higher than EC2 for consistent workloads
Complexity: More moving parts than simple EC2 setup

Cost Comparison

EC2: ~$25-50/month (predictable)
ECS Fargate: ~$30-80/month (scales with usage)

Production Tips

1. Use Secrets Manager

Never put sensitive data in environment variables:

import boto3

def get_secret(secret_name):
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId=secret_name)
    return response['SecretString']

2. Set Up Proper Logging

import logging
import json

# Structured logging for CloudWatch
class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_entry = {
            'timestamp': self.formatTime(record),
            'level': record.levelname,
            'message': record.getMessage(),
            'module': record.module
        }
        return json.dumps(log_entry)

# Configure logging
logging.basicConfig(level=logging.INFO)
handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logger = logging.getLogger(__name__)
logger.addHandler(handler)

3. Health Checks Matter

Make your health check meaningful:

@app.get("/health")
async def health_check():
    try:
        # Check database connection
        await database.execute("SELECT 1")
        return {"status": "healthy", "database": "connected"}
    except Exception as e:
        raise HTTPException(status_code=503, detail="Database connection failed")

Common Gotchas

Memory limits: Set them appropriately or containers get killed
Task definitions are immutable: You create new revisions, not edit existing ones
Security groups: ALB and ECS tasks need different security group rules
Logs: They go to CloudWatch, not local files

What's Next?

In Part 3, we'll explore the serverless approach with AWS Lambda. You'll see when it makes sense to go completely serverless and how to adapt your FastAPI application for Lambda.

We'll also compare all three approaches and help you decide which one fits your specific use case.

How has your experience been with containers? Are you using ECS, or have you tried other orchestration platforms? Share your thoughts in the comments!

Don't miss Part 3 - follow me to get notified when it's published!

Coming next: Part 3 - Going Serverless with Lambda

Previous: Part 1 - The EC2 Approach

fastapi #aws #docker #containers #ecs #devops #python #webdev #tutorial

Deploying FastAPI to AWS: Part 1 - The EC2 Approach (Learning the Fundamentals)

Nauman Tanwir — Sun, 13 Jul 2025 18:14:13 +0000

This is Part 1 of a 3-part series on deploying FastAPI applications to AWS. We'll start with EC2 to understand the fundamentals.

I just finished building my first real FastAPI application - a journal API with JWT authentication, PostgreSQL database, and all the features you'd expect. The app worked perfectly on my laptop, but then I hit the wall that every developer faces: how do I deploy this thing?

After trying different approaches and making plenty of mistakes, I decided to document what I learned. This series will cover three main ways to deploy FastAPI to AWS, starting with the most educational approach: EC2.

Why Start with EC2?

I know what you're thinking - "Isn't EC2 old school? Shouldn't I use containers or serverless?"

Here's the thing: starting with EC2 taught me networking, security, and infrastructure concepts that I use every day now. It's like learning to drive with a manual transmission - once you understand the fundamentals, everything else makes more sense.

What We're Building

Our FastAPI application has:

User authentication with JWT tokens
PostgreSQL database
Email functionality for password resets
RESTful endpoints for journal entries
Environment-based configuration

The goal is to deploy this securely on AWS with proper networking and database separation.

Architecture Overview

We'll create:

Internet Gateway → Public Subnet (FastAPI VM) → Private Subnet (PostgreSQL VM)

This setup teaches you:

VPC networking concepts
Security group configuration
Database security best practices
Server management fundamentals

Step 1: Setting Up the Network Infrastructure

Create the VPC

First, let's create our Virtual Private Cloud:

# Create VPC
aws ec2 create-vpc \
    --cidr-block 10.0.0.0/16 \
    --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=journal-api-vpc}]'

Create Subnets

We need a public subnet for our API server and a private subnet for the database:

# Public subnet for API server
aws ec2 create-subnet \
    --vpc-id vpc-xxxxxxxxx \
    --cidr-block 10.0.1.0/24 \
    --availability-zone us-east-1a \
    --tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=public-subnet}]'

# Private subnet for database
aws ec2 create-subnet \
    --vpc-id vpc-xxxxxxxxx \
    --cidr-block 10.0.2.0/24 \
    --availability-zone us-east-1a \
    --tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=private-subnet}]'

Internet Gateway and Routing

# Create and attach an internet gateway
aws ec2 create-internet-gateway \
    --tag-specifications 'ResourceType=internet-gateway,Tags=[{Key=Name,Value=journal-igw}]'

aws ec2 attach-internet-gateway \
    --vpc-id vpc-xxxxxxxxx \
    --internet-gateway-id igw-xxxxxxxxx

Step 2: Security Groups (This Is Important!)

Security groups are like firewalls for your instances. Getting this right is crucial for security.

API Server Security Group

# Create a security group for the API server
aws ec2 create-security-group \
    --group-name journal-api-sg \
    --description "Security group for FastAPI server" \
    --vpc-id vpc-xxxxxxxxx

# Allow HTTP traffic on port 8000
aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 8000 \
    --cidr 0.0.0.0/0

# Allow SSH for management
aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 22 \
    --cidr 0.0.0.0/0

Database Security Group

# Create a security group for the database
aws ec2 create-security-group \
    --group-name journal-db-sg \
    --description "Security group for PostgreSQL" \
    --vpc-id vpc-xxxxxxxxx

# Allow PostgreSQL access ONLY from the API server
aws ec2 authorize-security-group-ingress \
    --group-id sg-yyyyyyyyy \
    --protocol tcp \
    --port 5432 \
    --source-group sg-xxxxxxxxx

Key Point: Notice how the database only accepts connections from the API server security group, not from the entire internet. This is a fundamental security practice.

Step 3: Launch the Instances

API Server Instance

aws ec2 run-instances \
    --image-id ami-0c02fb55956c7d316 \
    --instance-type t3.micro \
    --key-name your-key-pair \
    --security-group-ids sg-xxxxxxxxx \
    --subnet-id subnet-xxxxxxxxx \
    --associate-public-ip-address \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=journal-api-server}]'

Database Instance

aws ec2 run-instances \
    --image-id ami-0c02fb55956c7d316 \
    --instance-type t3.micro \
    --key-name your-key-pair \
    --security-group-ids sg-yyyyyyyyy \
    --subnet-id subnet-yyyyyyyyy \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=journal-db-server}]'

Step 4: Setting Up the API Server

SSH into your API server and let's get FastAPI running:

# Update the system
sudo apt update && sudo apt upgrade -y

# Install Python 3.11
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev python3-pip git -y

# Clone your repository (replace with your repo)
git clone https://github.com/your-username/journal-api.git
cd journal-api

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Environment Configuration

Create your .env file with the database connection:

cat > .env << EOF
POSTGRES_HOST=10.0.2.xxx  # Private IP of your database server
POSTGRES_PORT=5432
POSTGRES_USER=journal_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=journal_db
SECRET_KEY=your_jwt_secret_key
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
EMAIL_SENDER=your_email@example.com
EMAIL_PASSWORD=your_app_password
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EOF

Step 5: Database Setup

Now let's set up PostgreSQL on the database server. You'll need to access it through a bastion host or AWS Systems Manager Session Manager since it's in a private subnet.

# Install PostgreSQL
sudo apt update
sudo apt install postgresql postgresql-contrib -y

# Start and enable PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create a database and a user
sudo -u postgres psql

In the PostgreSQL prompt:

CREATE DATABASE journal_db;
CREATE USER journal_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE journal_db TO journal_user;
\q

Configure PostgreSQL for Remote Access

Edit the configuration files:

# Edit postgresql.conf
sudo nano /etc/postgresql/15/main/postgresql.conf
# Change: listen_addresses = '*'

# Edit pg_hba.conf
sudo nano /etc/postgresql/15/main/pg_hba.conf
# Add: host    all    all    10.0.1.0/24    md5

# Restart PostgreSQL
sudo systemctl restart postgresql

Step 6: Deploy and Test

Back on your API server, run the database migrations:

cd journal-api
source venv/bin/activate
alembic upgrade head

Start your FastAPI application:

uvicorn app.main:app --host 0.0.0.0 --port 8000

Test it:

curl http://your-public-ip:8000/docs

Making It Production Ready

For a production setup, create a systemd service:

sudo tee /etc/systemd/system/journal-api.service > /dev/null <<EOF
[Unit]
Description=Journal API FastAPI application
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/journal-api
Environment=PATH=/home/ubuntu/journal-api/venv/bin
ExecStart=/home/ubuntu/journal-api/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable journal-api
sudo systemctl start journal-api

What I Learned

The Good:

Complete control over the environment
Great for understanding networking and security
Predictable costs
Easy to debug with direct SSH access

The Challenges:

Manual scaling (you handle load balancing yourself)
Ongoing maintenance (OS updates, security patches)
Single points of failure
More operational overhead

Cost: Around $25-50/month for a small application

Common Mistakes to Avoid

Opening security groups too wide - Only allow the minimum required access
Not setting up monitoring - At least enable CloudWatch basic monitoring
Forgetting backups - Set up automated database backups
Not using Elastic IP - Your public IP will change when you restart the instance

What's Next?

In Part 2, we'll look at containerizing this same application and deploying it with ECS Fargate. You'll see how containers solve many of the operational challenges we faced with EC2.

In Part 3, we'll explore the serverless approach with Lambda and see when it makes sense to go completely serverless.

Have you tried deploying FastAPI to EC2? What challenges did you face? Drop your questions in the comments - I'll answer them and might include solutions in the next parts of this series.

Found this helpful? Follow me for Parts 2 and 3 of this series!

Next up: Part 2 - Containerizing with ECS Fargate

fastapi #aws #python #webdev #devops #beginners #tutorial #ec2