Wild Beaver Climb - AI-Augmented Workspace Platform

An intelligent workspace platform that combines AI agents with visual workflow management to enhance productivity and collaboration.

🚀 Quick Start (Recommended)

Option 1: One-Click Startup (Easiest)

# Windows - Double-click one of these files:
start-dev.bat          # Batch file
start-dev.ps1          # PowerShell script (recommended)

# Or from command line:
npm run dev            # Requires concurrently package

Option 2: Manual Startup

# Terminal 1 - Backend
cd backend
python main.py

# Terminal 2 - Frontend  
cd frontend
npm run dev

🌐 Access URLs

• Frontend: http://localhost:5137
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

⚡ Features

• AI Agent Integration: Leverage multiple AI agents for different tasks and workflows
• Visual Workspace: Interactive node-based interface for managing projects and tasks
• Real-time Collaboration: Work together with team members in shared workspaces
• Document Management: Organize and manage documents within your workspace
• Authentication System: Secure user authentication and authorization

🏗️ Architecture

This project consists of two main components:

Frontend

• Framework: React with TypeScript
• Styling: Tailwind CSS
• Build Tool: Vite
• UI Components: Custom component library with shadcn/ui
• State Management: React Context API
• Port: 5137

Backend

• Framework: FastAPI (Python)
• Database: MongoDB
• Authentication: JWT-based authentication
• API: RESTful API with automatic OpenAPI documentation
• Port: 8000

📁 Project Structure

├── frontend/                    # React frontend application
│   ├── src/
│   │   ├── components/          # Reusable UI components
│   │   ├── contexts/            # React context providers
│   │   ├── pages/               # Page components
│   │   ├── lib/                 # Utility functions and API client
│   │   └── hooks/               # Custom React hooks
│   ├── public/                  # Static assets
│   └── package.json             # Frontend dependencies
│
├── backend/                     # FastAPI backend application
│   ├── models/                  # Database models
│   ├── routers/                 # API route handlers
│   ├── utils/                   # Utility functions
│   ├── main.py                  # Application entry point
│   └── requirements.txt         # Backend dependencies
│
├── start-dev.bat               # Windows startup script
├── start-dev.ps1               # PowerShell startup script
├── package.json                # Root package.json with dev scripts
├── DEVELOPMENT_TROUBLESHOOTING_GUIDE.md  # Comprehensive troubleshooting
└── README.md                   # This file

🛠️ Installation & Setup

Prerequisites

• Node.js (v18 or higher)
• Python (v3.8 or higher)
• npm or pnpm

Quick Setup

# Install all dependencies
npm run install:all

# Start both servers
npm run dev

Manual Setup

Frontend Setup

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install
# or
pnpm install

3. Start the development server:

npm run dev
# or
pnpm dev

The frontend will be available at http://localhost:5137

Backend Setup

1. Navigate to the backend directory:

cd backend

2. Create a virtual environment:

python -m venv venv

3. Activate the virtual environment:

# Windows
venv\Scripts\activate
# or PowerShell
.\venv\Scripts\Activate.ps1

# macOS/Linux
source venv/bin/activate

4. Install dependencies:

pip install -r requirements.txt

5. Start the development server:

python main.py

The backend API will be available at http://localhost:8000 API documentation will be available at http://localhost:8000/docs

🔧 Troubleshooting

Common Issues

• Port 5137 not loading: Frontend server not running → Use startup scripts or cd frontend && npm run dev
• API calls failing: Backend server not running → Use startup scripts or cd backend && python main.py
• Port conflicts: Check what's using the ports with netstat -ano | findstr :5137 or netstat -ano | findstr :8000

Comprehensive Guide

See DEVELOPMENT_TROUBLESHOOTING_GUIDE.md for detailed troubleshooting steps and solutions.

⚙️ Configuration

Environment Variables

Create a .env file in the backend directory with the following variables:

DATABASE_URL=mongodb://localhost:27017/wild_beaver_climb
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

📚 API Documentation

Once the backend is running, you can access the interactive API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🚀 Development

Frontend Development

• Uses Vite for fast development and hot module replacement
• TypeScript for type safety
• Tailwind CSS for styling
• ESLint for code linting

Backend Development

• FastAPI for modern Python web API development
• MongoDB for database
• Pydantic for data validation
• Automatic API documentation generation

📦 Available Scripts

Root Level

• npm run dev - Start both frontend and backend servers
• npm run install:all - Install all dependencies
• npm run setup - Install dependencies and start servers

Frontend

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build

Backend

• python main.py - Start development server

🚀 Deployment

Frontend Deployment

The frontend can be deployed to platforms like Vercel, Netlify, or any static hosting service:

cd frontend
npm run build

Backend Deployment

The backend can be deployed to platforms like Railway, Heroku, or any cloud provider that supports Python applications.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with modern web technologies
• Inspired by the need for intelligent workspace management
• Thanks to the open-source community for the amazing tools and libraries

---

Need Help? Check the troubleshooting guide or create an issue.