Epiminds - AI Agent Development System

A Next.js application featuring three specialized AI agents powered by GPT-4o that collaborate to build complete software features through intelligent communication.

✨ Features

🎨 UI/UX Designer Agent: Analyzes requirements and creates comprehensive design proposals with user experience patterns, wireframes, and visual specifications
⚛️ Frontend Developer Agent: Implements production-ready React/Next.js 16 components with TypeScript, state management, and responsive styling
🔧 Backend Developer Agent: Builds secure API endpoints, database schemas, and server-side logic
📨 Message Bus: Pub/sub communication system enabling seamless agent-to-agent collaboration
💬 Interactive Chat Interface: Beautiful chatbot UI with expandable code sections and full agent output display
🔄 Multiple Workflow Modes: Sequential (coordinated) or parallel (fast) execution

📋 Prerequisites

Node.js 18 or higher
npm or yarn package manager
OpenAI API key (Get one here)

🚀 Getting Started

Clone the repository:

git clone https://github.com/jaggernaut007/js-coding-agent.git
cd epiminds

Install dependencies:
```
npm install
```
Configure environment variables:

Create a .env.local file in the root directory:
```
OPENAI_API_KEY=sk-your-actual-openai-api-key-here
```
Important: Never commit your API key to version control. The .env.local file is already in .gitignore.
Run the development server:
```
npm run dev
```
Open your browser:

Navigate to http://localhost:3000
Start building:

Type a feature request like "Create a user authentication system" and watch the agents collaborate!

🏗️ How It Works

Agent Architecture

The system uses three specialized AI agents, each powered by GPT-4o:

🎨 UI/UX Designer Agent (UIUXDesignerAgent.ts)
- Analyzes user requirements and personas
- Creates comprehensive design proposals with wireframes
- Defines visual design specifications (colors, typography, spacing)
- Ensures WCAG accessibility compliance
- Considers responsive design for all screen sizes
- Provides detailed component specifications
⚛️ Frontend Developer Agent (FrontendDeveloperAgent.ts)
- Receives design proposals from UI/UX Designer
- Implements production-ready React/Next.js 16 components
- Ensures full TypeScript type safety
- Handles state management and client-side logic
- Implements responsive layouts and styling
- Requests backend APIs when needed
- Optimizes for performance and accessibility
🔧 Backend Developer Agent (BackendDeveloperAgent.ts)
- Designs RESTful API endpoints and data models
- Implements Next.js 16 API routes with proper validation
- Creates database schemas (when needed)
- Handles authentication and authorization
- Implements security best practices (OWASP)
- Provides API documentation and integration specs
- Optimizes database queries and performance

📨 Message Bus Communication

The MessageBus class enables sophisticated pub/sub communication:

Subscription Model: Agents subscribe to receive messages
Direct & Broadcast: Messages can target specific agents or broadcast to all
Message History: Full communication log for debugging and tracking
Type-Safe Messages: Strongly typed message structure with TypeScript
Message Types:
- task_started - Initiates workflow
- design_proposal - Design sent to frontend
- frontend_implementation - Code sent to backend
- backend_implementation - API specs shared
- question / answer - Inter-agent queries
- progress_update - Status notifications
- error - Error handling

🔄 Workflow Modes

Sequential Mode (default - recommended):

🎨 UI/UX Designer analyzes requirements and creates design
⚛️ Frontend Developer receives design and implements components
🔧 Backend Developer (if needed) creates APIs based on frontend needs
Agents collaborate through questions and feedback

Parallel Mode (experimental):

All three agents work simultaneously on the same request
Faster execution but less coordination
Best for independent, non-overlapping tasks

📡 API Endpoints

`/api/health`

Health check endpoint for monitoring

GET /api/health

Response:

{
  "status": "ok",
  "timestamp": "2025-12-03T12:34:56.789Z",
  "uptime": 123.45,
  "environment": "development"
}

`/api/agents/chat`

Main endpoint for agent interaction

POST /api/agents/chat

Request:

{
  "message": "Build a user profile page with avatar upload",
  "mode": "sequential"  // or "parallel"
}

Response:

{
  "success": true,
  "data": {
    "design": "Full UI/UX design proposal...",
    "frontend": "Complete React component code...",
    "backend": "API routes and database schema...",
    "messages": [
      {
        "from": "UIUXDesigner",
        "to": "FrontendDeveloper",
        "type": "design_proposal",
        "timestamp": "2025-12-03T12:34:56.789Z"
      }
    ]
  }
}

GET /api/agents/chat

Returns current status of all agents

Response:

{
  "status": "ok",
  "agents": {
    "initialized": true,
    "agents": {
      "uiux": { "name": "UIUXDesigner", "role": "UI/UX Designer" },
      "frontend": { "name": "FrontendDeveloper", "role": "Frontend Developer" },
      "backend": { "name": "BackendDeveloper", "role": "Backend Developer" }
    }
  }
}

📁 Project Structure

epiminds/
├── app/
│   ├── api/
│   │   ├── agents/
│   │   │   └── chat/
│   │   │       └── route.ts          # Main agent API endpoint
│   │   └── health/
│   │       └── route.ts              # Health check endpoint
│   ├── components/
│   │   └── ChatBot.tsx               # Interactive chat interface with expandable outputs
│   ├── layout.tsx                    # Root layout with metadata
│   ├── page.tsx                      # Home page
│   └── globals.css                   # Global styles and animations
├── lib/
│   └── agents/
│       ├── Agent.ts                  # Base agent class with LLM integration
│       ├── MessageBus.ts             # Pub/sub communication system
│       ├── UIUXDesignerAgent.ts      # UI/UX Designer implementation
│       ├── FrontendDeveloperAgent.ts # Frontend Developer implementation
│       ├── BackendDeveloperAgent.ts  # Backend Developer implementation
│       └── AgentOrchestrator.ts      # Coordinates agent workflows
├── .env.local                        # Environment variables (not in git)
├── .gitignore                        # Git ignore rules
├── package.json                      # Dependencies and scripts
├── tsconfig.json                     # TypeScript configuration
├── next.config.js                    # Next.js configuration
└── README.md                         # This file

💡 Usage Examples

Example 1: Build a Todo List

Input:

Create a todo list with add, delete, and mark complete features

Output:

🎨 Design: Component layout, color scheme, interaction patterns
⚛️ Frontend: Complete React component with state management
🔧 Backend: API endpoints for CRUD operations

Example 2: User Authentication

Input:

Build a user authentication system with email/password login

Output:

🎨 Design: Login/signup forms, error states, responsive design
⚛️ Frontend: Form validation, authentication flow, protected routes
🔧 Backend: JWT authentication, password hashing, session management

Example 3: Dashboard with Analytics

Input:

Create an admin dashboard with user statistics and charts

Output:

🎨 Design: Dashboard layout, chart specifications, data visualization
⚛️ Frontend: Chart components, data fetching, responsive grid
🔧 Backend: Analytics API, data aggregation, database queries

Chat Interface Features

The chatbot UI provides:

Expandable Sections: Click ▶ to expand each agent's output
Code Display: Syntax-highlighted code blocks with dark theme
Full Output: No truncation - see complete designs and code
Message History: Track agent-to-agent communication
Scrollable Content: Long outputs are scrollable within sections

🛠️ Development

Available Scripts

npm run dev      # Start development server (hot reload enabled)
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run ESLint for code quality

Development Features

🔥 Hot Reload: Changes reflected immediately without restart
📘 TypeScript: Full type safety across the entire codebase
✅ ESLint: Automated code quality and style checks
📊 Message History: All agent communications logged in browser console
🐛 Error Handling: Comprehensive error messages and recovery
⚡ Fast Refresh: React Fast Refresh for instant UI updates

Key Technologies

Framework: Next.js 16 with App Router
Language: TypeScript 5.3+
AI/LLM: OpenAI GPT-4o via Vercel AI SDK
Styling: CSS-in-JS with inline styles
Architecture: Agent-based with message bus pattern

🐛 Troubleshooting

"OpenAI API key not configured"

Problem: API key is missing or incorrect

Solutions:

Ensure .env.local file exists in the project root
Verify OPENAI_API_KEY=sk-... is correctly set
Restart the development server after adding the key
Check that the key starts with sk- and is valid on OpenAI platform

Agents taking too long / Timeout errors

Problem: Agents exceed 15-second timeout

Solutions:

Check your OpenAI API rate limits and usage quota
Simplify your request to reduce processing time

Adjust timeout in AgentOrchestrator.ts (line ~120):

await this.waitForCompletion(30000) // Increase to 30 seconds

Try parallel mode for faster (but less coordinated) execution

Type errors or compilation issues

Problem: TypeScript or build errors

Solutions:

Run npm install to ensure all packages are installed
Delete .next folder and rebuild: rm -rf .next && npm run dev
Check tsconfig.json is properly configured
Verify Node.js version is 18 or higher: node --version

Chat interface not responding

Problem: Messages sent but no response

Solutions:

Check browser console for JavaScript errors
Verify OpenAI API key is valid and has credits
Check network tab in DevTools for failed API requests
Restart the development server

"Cannot find module" errors

Problem: Missing dependencies

Solutions:

Delete node_modules and reinstall: rm -rf node_modules && npm install
Clear npm cache: npm cache clean --force
Check package.json for correct dependency versions

🏗️ Architecture Highlights

Agent System Design

Each agent is:

Autonomous: Makes independent decisions based on its expertise
Collaborative: Communicates with other agents via message bus
Stateful: Maintains conversation history and scratchpad data
Type-Safe: Fully typed with TypeScript interfaces

Message Bus Pattern

The pub/sub architecture enables:

Decoupling: Agents don't directly depend on each other
Scalability: Easy to add new agents to the system
Traceability: Full message history for debugging
Flexibility: Direct messages or broadcasts

Best Practices Implemented

✅ Separation of concerns (each agent has clear responsibilities)
✅ Clean architecture with distinct layers
✅ Type safety throughout the codebase
✅ Error handling and recovery mechanisms
✅ Extensible design for future enhancements
✅ Comprehensive system prompts for agent behavior

🚀 Future Enhancements

Potential improvements and features:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Shreyas Jagannath

GitHub: @jaggernaut007
Repository: js-coding-agent

🙏 Acknowledgments

Next.js - The React framework
Vercel AI SDK - AI/LLM integration
OpenAI - GPT-4o language model
TypeScript - Type safety

Built with ❤️ using Next.js and GPT-4o

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
app		app
lib/agents		lib/agents
.gitignore		.gitignore
CHATBOT_UPDATES.md		CHATBOT_UPDATES.md
README.md		README.md
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
plan.md		plan.md
tsconfig.json		tsconfig.json

jaggernaut007/js-coding-agent

Folders and files

Latest commit

History

Repository files navigation

Epiminds - AI Agent Development System

✨ Features

📋 Prerequisites

🚀 Getting Started

🏗️ How It Works

Agent Architecture

📨 Message Bus Communication

🔄 Workflow Modes

📡 API Endpoints

/api/health

/api/agents/chat

📁 Project Structure

💡 Usage Examples

Example 1: Build a Todo List

Example 2: User Authentication

Example 3: Dashboard with Analytics

Chat Interface Features

🛠️ Development

Available Scripts

Development Features

Key Technologies

🐛 Troubleshooting

"OpenAI API key not configured"

Agents taking too long / Timeout errors

Type errors or compilation issues

Chat interface not responding

"Cannot find module" errors

🏗️ Architecture Highlights

Agent System Design

Message Bus Pattern

Best Practices Implemented

🚀 Future Enhancements

🤝 Contributing

📄 License

👨‍💻 Author

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`/api/health`

`/api/agents/chat`

Packages