Tech Stack Advisor - Code Viewer

# Tech Stack Advisor - Quick Start Guide

## 🚀 Get Started in 3 Minutes

### Prerequisites
- Python 3.11+
- 10 MB disk space
- Internet connection (for API keys)

---

## Step 1: Clone & Setup (1 min)

```bash
# Clone repository
git clone https://github.com/ranjanarajendran/tech-stack-advisor.git
cd tech-stack-advisor

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"
```

---

## Step 2: Configure (30 sec)

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your API keys
# You need:
# - ANTHROPIC_API_KEY (get from https://console.anthropic.com)
# - QDRANT_URL & QDRANT_API_KEY (optional, use --local for testing)
```

---

## Step 3: Run! (30 sec)

### Option A: Recommended (One Command)

```bash
./run_app.sh
```

Then open: **http://localhost:8000**

### Option B: Manual Start

```bash
python -m backend.src.api.main
```

Server available at: **http://localhost:8000**
- **Web UI**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs
- **Login**: http://localhost:8000/login.html
- **Admin**: http://localhost:8000/admin.html

---

## 🎯 Try It Out

### In the Web UI:
1. Visit http://localhost:8000
2. Register/Login (or use Google OAuth)
3. Enter a query like:
   ```
   "Building a chat app for 100K daily users with real-time messaging"
   ```
4. Click "Get Recommendations"
5. View results from 4 AI agents
6. Download JSON report

### Via API:
```bash
curl -X POST http://localhost:8000/recommend \
  -H "Content-Type: application/json" \
  -d '{"query":"Chat app for 100K users"}'
```

---

## 📊 What You Get

**5 Specialized AI Agents analyze your requirements:**

1. **💬 Conversation Manager Agent**
   - Conducts intelligent multi-turn dialogues
   - Asks targeted follow-up questions
   - Extracts and accumulates project context
   - Determines when to generate recommendations

2. **🗄️ Database Agent**
   - Recommends databases (PostgreSQL, MongoDB, Redis, etc.)
   - Provides scaling strategies
   - Estimates connections & cache needs

3. **☁️ Infrastructure Agent**
   - Suggests cloud provider (AWS, GCP, Azure, Railway)
   - Recommends architecture (monolith, microservices, serverless)
   - Provides deployment strategy

4. **💰 Cost Agent**
   - Compares costs across providers
   - Estimates monthly & annual costs
   - Provides optimization tips

5. **🔒 Security Agent**
   - Performs threat modeling
   - Checks compliance (GDPR, HIPAA, PCI-DSS, SOC 2)
   - Recommends security measures

---

## 🔧 Troubleshooting

### API won't start
```bash
# Check if port 8000 is in use
lsof -i :8000

# Kill existing process
kill -9 <PID>
```

### Can't access UI
1. Make sure backend is running: `curl http://localhost:8000/health`
2. Check port 8000 is not in use by another process
3. Try opening http://localhost:8000 in browser

### "Unauthorized" errors
1. Register a new account at http://localhost:8000/register.html
2. Or login at http://localhost:8000/login.html
3. JWT token will be stored automatically

### NumPy errors
```bash
pip install "numpy<2"
```

---

## 📚 Next Steps

### Learn More
- 📖 [Full Documentation](./README.md)
- 🏗️ [Architecture Details](./AGENTS_IMPLEMENTATION.md)
- 🔌 [API Reference](http://localhost:8000/docs)
- 🎨 [Frontend Guide](./FRONTEND_IMPLEMENTATION.md)

### Add Knowledge
```bash
# Load knowledge base into vector store
python scripts/ingest_knowledge.py --local  # Test locally
python scripts/ingest_knowledge.py          # Production (Qdrant Cloud)
```

### Run Tests
```bash
python test_agents.py      # Test agents
python test_workflow.py    # Test LangGraph
python test_api.py         # Test API
```

### Deploy
- **Railway**: `railway up`
- **Render**: Connect GitHub repo
- **Docker**: `docker-compose up`

---

## 🎓 Example Queries

### Startup MVP
```
"Building an MVP for a task management app with 5K users,
 need something simple and cheap"
```

### Growing Product
```
"E-commerce platform with 50K DAU, real-time inventory,
 payment processing, budget $1000/month"
```

### Enterprise Scale
```
"Healthcare platform for 500K daily users, HIPAA compliant,
 real-time telemedicine, multi-region deployment"
```

### Compliance-Heavy
```
"Financial services app with payment processing,
 need GDPR + PCI-DSS compliance, 100K transactions/day"
```

---

## 💰 Costs

### Free Tier (Testing)
- Anthropic: First $5 free
- Qdrant: 1GB free
- **Total: $0** for testing

### Production (100 queries/day)
- Anthropic API: ~$4.50/month
- Qdrant Cloud: Free tier
- Hosting: ~$5/month (Railway)
- **Total: ~$10/month**

---

## 🆘 Get Help

- **Documentation**: All `.md` files in repo
- **API Docs**: http://localhost:8000/docs
- **Issues**: https://github.com/ranjanarajendran/tech-stack-advisor/issues
- **Discussions**: GitHub Discussions

---

## ✅ Quick Checklist

- [ ] Python 3.11+ installed
- [ ] Virtual environment created
- [ ] Dependencies installed
- [ ] `.env` file configured
- [ ] API starts successfully
- [ ] UI opens in browser
- [ ] First query completes
- [ ] Downloaded JSON results

**All done? You're ready to go! 🚀**

---

**Estimated Time:** 3 minutes
**Difficulty:** Easy
**Prerequisites:** Basic command line skills

Happy building! 🎉