🏭 Agentic SDLC Factory

Scalable AI engineering ecosystem that orchestrates specialized agent containers via Redis Queue communication. Cloud-hosted Jira Listener + Local AI Agents + Full-Stack Application Services.

---

🚀 Quick Start

# 1. Configure
cp .env.example .env
# Edit .env with your values

# 2. Start everything
docker-compose --profile ai up -d --build

# 3. Monitor
open http://localhost:3000

# That's it! ✨

See QUICK_REFERENCE.md for detailed commands.

---

🏗️ Architecture

3-Tier System in One docker-compose.yml

┌─────────────────────────────────────────┐
│ TIER 1: Application Services            │
│ ├─ PostgreSQL (5432)                    │
│ ├─ Backend API (8080) Python            │
│ └─ Frontend UI (4200) Angular           │
├─────────────────────────────────────────┤
│ TIER 2: AI Orchestration (Redis Queue)  │
│ ├─ 11 RQ Workers (agents)               │
│ └─ Ollama LLM (11434)                   │
├─────────────────────────────────────────┤
│ TIER 3: Monitoring                      │
│ └─ Dashboard (3000) Real-time UI        │
│    (queries Redis directly)             │
└─────────────────────────────────────────┘

Tier	Service	Port	Tech
App	PostgreSQL	5432	postgres:15-alpine
App	Backend API	8080	Python 3.11 + FastAPI
App	Frontend UI	4200	Node 18 + Angular 17
AI	Jira Listener (Cloud)	8000	FastAPI (no AI deps)
AI	11 RQ Agents (Local)	-	Python + RQ + CrewAI
AI	Ollama LLM (Local)	11434	Ollama
Monitor	Dashboard	3000	Node 18 + Express (queries Redis)

---

📊 Queue System (11 Queues)

Queue	Agent	Context
agent-analyze	Analyst	-
agent-backend	Backend Dev	backend
agent-frontend	Frontend Dev	frontend
agent-git	Git Manager	any
agent-integration	Tester	any
agent-security	SecOps	any
agent-review	Reviewer	any
agent-docs	Doc Architect	any
agent-finalize	Finalizer	any
agent-fix-backend	Backend Fixer	backend
agent-fix-frontend	Frontend Fixer	frontend

Context-aware routing: Backend/Frontend fixes go to separate queues.

---

📂 Project Structure

ai-sdlc-factory/
├── docker-compose.yml           ← Main (everything)
├── Dockerfile                   ← Agents base
├── Dockerfile.backend           ← Backend container
├── Dockerfile.frontend          ← Frontend container
├── .env.example                 ← Config template
│
├── backend/                     ← Auto-cloned from git
├── frontend/                    ← Auto-cloned from git
│
├── listener/                    ← Cloud deployment
├── ai-agents-core/              ← Workers + agents
├── monitoring-ui/               ← Dashboard
│
└── Documentation:
    ├── README.md (this file)
    ├── QUICK_REFERENCE.md
    ├── DEPLOYMENT_CHECKLIST.md
    ├── DOCKERFILE_TEMPLATES.md
    └── SUMMARY_OF_CHANGES.md

---

💡 How It Works

1. Application Layer

• PostgreSQL stores data
• Backend API runs FastAPI server
• Frontend UI runs Angular app
• Integration agent tests against these services

2. Agent Layer

• Jira Listener (cloud) receives webhooks
• Enqueues jobs to Redis queues
• 11 workers consume and process
• Each worker runs a specialized agent (Analyst, Backend Dev, etc.)

3. Monitoring Layer

• Dashboard shows real-time metrics
• 11 agents + 11 queues tracked
• Event stream logs all activities

Auto-Git: Backend/Frontend pull latest from master branch on each deployment.

---

🔄 Workflow

Jira Issue → Listener → analyze queue
           → agent-analyze (posts plan)
           → awaiting human approval
           → (after "proceed") → agent-backend/frontend
           → agent-git (creates branch)
           → agent-integration (tests against running services)
           → agent-security (scans)
           → agent-review (reviews PR)
           → Completed ✅

---

📋 Environment Variables

Copy .env.example to .env and set:

# Database
DB_USER=admin
DB_PASSWORD=admin
DB_NAME=sdlc_app

# Repos (auto-cloned on container start)
BACKEND_REPO_URL=https://github.com/org/backend.git
FRONTEND_REPO_URL=https://github.com/org/frontend.git

# Redis (Cloud or local)
REDIS_URL=rediss://default:password@host:port

# GitHub (for git operations)
GITHUB_TOKEN=ghp_xxxxx
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=your@email.com

# Jira (for webhook listener on cloud)
JIRA_DOMAIN=yourorg.atlassian.net
JIRA_USERNAME=your@email.com
JIRA_API_TOKEN=xxxxx

# LLM (local or remote)
OLLAMA_HOST=http://localhost:11434

---

⚠️ Common Issues

Pip dependency resolver timeout during build?

• The requirements.txt includes langchain and crewai with many transitive dependencies
• First build may take 5-15 minutes as pip resolves all constraints
• Subsequent builds are much faster (Docker caches layers)
• If it times out, check your internet connection or try building individual containers:

  docker-compose build --no-cache backend-api  # Test non-agent container first

Repos not cloning?

• Ensure BACKEND_REPO_URL and FRONTEND_REPO_URL point to valid git repos
• Repos must have requirements.txt (backend) and package.json (frontend)
• Check credentials in .env have proper permissions

Worker failing with "Invalid attribute name: 1"?

• This occurs if the rq worker command uses the -w flag incorrectly.
• In RQ, -w is short for --worker-class, not the number of workers.
• Fix: Use --name [worker-name] instead of -w 1.

✅ Verification

# Check services
docker ps | grep ai-sdlc

# Test endpoints
curl http://localhost:8080/docs        # Backend
open http://localhost:4200             # Frontend
open http://localhost:3000             # Dashboard

# Check queues
rq info -i 1

# Check workers
docker logs agent-analyze

---

🚢 Deployment

Local Development (All-in-one)

docker-compose --profile ai up -d --build

Production: Cloud-Local Hybrid

Cloud (lightweight listener only):

# Deploy listener/ to any cloud platform
# Receives Jira webhooks → pushes to Redis
# Image: ~100MB, no AI dependencies

Local (agents + app + monitoring):

# Keep running locally/on-prem with full stack
docker-compose --profile ai up -d --build

# Access:
# - Frontend: http://localhost:4200
# - Backend: http://localhost:8080/docs
# - Dashboard: http://localhost:3000

Architecture:

• Jira → Cloud Listener (8000) → Redis Cloud
• Redis Cloud ← Local Agents (consume & process)
• App Services (DB, Backend, Frontend) run locally
• Monitoring queries Redis directly

See DEPLOYMENT_CHECKLIST.md for step-by-step guide.

---

📚 Documentation

File	Purpose
QUICK_REFERENCE.md	Commands, startup, status checks
DEPLOYMENT_CHECKLIST.md	Production deployment steps
DOCKERFILE_TEMPLATES.md	Docker architecture & setup
SUMMARY_OF_CHANGES.md	What changed & why

---

🔌 Endpoints

Service	Endpoint	Purpose
Backend	http://localhost:8080/docs	API docs
Frontend	http://localhost:4200	UI
Dashboard	http://localhost:3000	Real-time monitoring (queries Redis)
Listener	https://your-url/webhook/jira	Jira webhook endpoint

---

🆘 Troubleshooting

Services not starting?

docker-compose down
docker-compose --profile ai up -d --build

Database error?

docker logs ai-sdlc-db
docker exec -it ai-sdlc-db psql -U admin -d sdlc_app -c "SELECT 1;"

Agents stuck?

docker logs agent-backend
rq info
redis-cli -u $REDIS_URL PING

See DEPLOYMENT_CHECKLIST.md for more.

---

🎯 Key Features

✅ Cloud-Local Hybrid - Listener on cloud, agents local
✅ Pure Redis - No HTTP between services
✅ Full-Stack - Database + Backend + Frontend included
✅ Auto-Git - Repos pull latest on startup
✅ Integration Testing - Agents test against running services
✅ Real-Time Monitoring - Dark theme dashboard
✅ Context-Aware - Separate queues for backend/frontend
✅ Production-Ready - Single docker-compose.yml

---

📦 Tech Stack

• Queue: RQ (Redis Queue) — Pure Redis, no message broker
• Agents: CrewAI + LiteLLM (supports Ollama, Groq, OpenAI, etc.)
• LLM: Ollama (local) or cloud providers
• Backend: Python 3.11 + FastAPI
• Frontend: Angular 17 + Node.js 18
• Database: PostgreSQL 15
• Monitoring: Express.js + Node.js (queries Redis directly)
• Infrastructure: Docker Compose (3-tier stack in one file)
• Listener: FastAPI (cloud-native, no AI dependencies)

---

📝 License

Open source. Contributions welcome!

---

Questions? See DEPLOYMENT_CHECKLIST.md for detailed setup & troubleshooting.