AI Agent Registry & Discovery Portal

A production-grade platform for registering, discovering, and managing AI agents and tools within an organization. Includes a Hackathon & Idea Management Module with dual entry paths (hackathon ideas → tool promotion, and direct tool submission).

Architecture

├── backend/          # FastAPI (Python 3.12)
├── frontend/         # Next.js 14 + Tailwind CSS
├── database/         # PostgreSQL schema & seed data
└── docker-compose.yml

Features

Tool Registry

• Submit, search, and discover AI tools with full metadata
• Multi-stage approval pipeline (Domain → Risk → Tech)
• AI-powered tag suggestions
• Duplicate/similar tool detection
• Comments and interest tracking
• Version history with snapshots

Hackathon & Idea Management

• Dual entry system: Submit Ideas (hackathon path) or Submit Tools (direct path)
• Hackathon lifecycle: Draft → Open → Judging → Closed
• Idea submission with team members, duplicate checking
• Hackathon submissions with screenshots
• Promote submission → Tool with one click (auto-fills from idea data)
• Source-wise analytics tracking conversion rates

Dashboard & Analytics

• KPI cards: total tools, ideas, hackathons, conversion rates
• Tools by source (hackathon vs direct vs external)
• Approval pipeline status
• Source → production conversion rates
• Top domains

Admin Panel

• User management with role assignment (viewer/submitter/reviewer/admin)
• Domain & tag CRUD
• Audit log

Quick Start

Docker (Recommended)

cd AgentsDiscovery

# Start all services
docker compose up --build

# Access:
#   Frontend:  http://localhost:3000
#   Backend:   http://localhost:8000
#   API Docs:  http://localhost:8000/docs

Manual Setup

1. Database

# Create PostgreSQL database
createdb agent_registry
psql agent_registry < database/schema.sql

2. Backend

cd backend
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/Mac

pip install -r requirements.txt

# Set environment variables
set DATABASE_URL=postgresql://user:pass@localhost:5432/agent_registry
set SECRET_KEY=your-secret-key

uvicorn app.main:app --reload --port 8000

3. Frontend

cd frontend
npm install
npm run dev
# Opens at http://localhost:3000

API Overview

Endpoint	Description
POST /api/auth/register	Register user
POST /api/auth/login	Login (OAuth2 form)
GET /api/tools	List/search tools
POST /api/tools	Submit new tool
GET /api/tools/{id}/similar	Find similar tools
POST /api/approvals/{tool_id}/{stage}	Process approval
GET /api/dashboard/stats	Dashboard KPIs
POST /api/hackathons	Create hackathon
POST /api/ideas	Submit idea
GET /api/ideas/check-duplicates	Check for duplicate ideas
POST /api/submissions	Create hackathon submission
POST /api/submissions/{id}/promote	Promote submission → tool
GET /api/hackathons/analytics/summary	Hackathon analytics
GET /api/admin/audit-log	Audit log

Full interactive docs at /docs (Swagger) or /redoc.

Tech Stack

Backend: FastAPI, SQLAlchemy 2.0, PostgreSQL, JWT auth, Pydantic v2
Frontend: Next.js 14, React 18, Tailwind CSS, Recharts, Lucide Icons
Deployment: Docker Compose with PostgreSQL

Environment Variables

Variable	Default	Description
DATABASE_URL	(required)	PostgreSQL connection string
SECRET_KEY	(required)	JWT signing key
CORS_ORIGINS	["http://localhost:3000"]	Allowed CORS origins
NEXT_PUBLIC_API_URL	/api	Backend API URL for frontend