Getting Started

Welcome to the BOSS Platform! This guide will help you set up your development environment and get the platform running locally.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18.0 or higher)
npm or yarn package manager
Git for version control
Go (v1.21 or higher) for backend
MongoDB (v6.0 or higher) for database
Redis (v7.0 or higher) for caching
Docker (optional, for containerized development)

Quick Start

1. Clone the Repository

git clone https://github.com/your-org/boss-monorepo.git
cd boss-monorepo

2. Install Dependencies

# Install root dependencies
npm install

# Install web app dependencies
cd apps/web
npm install

# Install documentation dependencies
cd ../docs
npm install

3. Environment Setup

Create environment files for each application:

Web Application (.env.local)

cd apps/web
cp .env.example .env.local

Edit .env.local:

# Database
DATABASE_URL="mysql://user:password@localhost:3306/dashboard_db"

# Authentication
JWT_SECRET="your-secret-key-min-32-characters"
JWT_REFRESH_SECRET="your-refresh-secret-key"

# API Configuration
NEXT_PUBLIC_API_URL="http://localhost:3000/api"
NEXT_PUBLIC_WS_URL="ws://localhost:3000/ws"

# Features
NEXT_PUBLIC_ENABLE_ANALYTICS=true
NEXT_PUBLIC_ENABLE_REALTIME=true

4. Database Setup

MongoDB Setup

# Option 1: Local MongoDB
# Make sure MongoDB is running locally on port 27017

# Option 2: MongoDB Atlas (Cloud)
# Create a free cluster at https://www.mongodb.com/cloud/atlas
# Get your connection string

# Option 3: Docker MongoDB
docker run -d -p 27017:27017 --name boss-mongodb \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  mongo:6.0

# Update backend/.env with MongoDB connection string
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=boss_db

# Or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net
# MONGODB_DATABASE=boss_db

Redis Setup

# Option 1: Local Redis
# Make sure Redis is running locally on port 6379

# Option 2: Docker Redis
docker run -d -p 6379:6379 --name boss-redis redis:7-alpine

# Update backend/.env with Redis connection
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

5. Start Development Servers

# Terminal 1: Start Go backend
cd apps/backend
go run cmd/server/main.go
# Backend will run on http://localhost:8080

# Terminal 2: Start Next.js frontend
cd apps/web
npm run dev
# Frontend will run on http://localhost:3000

# Terminal 3: Start documentation site (optional)
cd apps/docs
npm run start
# Docs will run on http://localhost:3001

Access the applications:

Backend API: http://localhost:8080
Web App: http://localhost:3000
API Health: http://localhost:8080/health
Documentation: http://localhost:3001

Project Structure

boss-monorepo/
├── apps/
│   ├── backend/             # Go REST API
│   │   ├── cmd/server/     # Main application entry
│   │   ├── internal/
│   │   │   ├── api/       # HTTP handlers & routes
│   │   │   ├── models/    # Data models (21 models)
│   │   │   ├── repository/# MongoDB repositories
│   │   │   ├── service/   # Business logic layer
│   │   │   ├── middleware/# Auth, RBAC, Audit
│   │   │   ├── tools/     # Tool execution framework
│   │   │   └── config/    # Configuration
│   │   └── pkg/          # Shared packages
│   │
│   ├── web/                # Next.js Frontend
│   │   ├── src/
│   │   │   ├── app/      # App router pages
│   │   │   ├── components/# React components
│   │   │   ├── lib/      # Utilities
│   │   │   ├── store/    # Zustand stores
│   │   │   └── services/ # API client services
│   │   └── public/       # Static assets
│   │
│   ├── docs/              # Documentation (Docusaurus)
│   │   ├── docs/         # Markdown docs
│   │   └── src/          # Doc components
│   │
│   └── agents/            # Python AI agents (LangChain)
│
└── postman/               # API collection & environment

Development Workflow

1. Feature Development

2. Branch Naming Convention

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation updates
refactor/description - Code refactoring
test/description - Test additions

3. Commit Message Format

type(scope): description

[optional body]

[optional footer]

Examples:

feat(tickets): add bulk ticket assignment
fix(dashboard): resolve widget rendering issue
docs(api): update authentication guide

Configuration Deep Dive

Database Configuration

The platform uses MongoDB with the official Go driver. Example model:

// internal/models/ticket.go
type Ticket struct {
    ID              primitive.ObjectID   `bson:"_id,omitempty" json:"id"`
    TicketID        string              `bson:"ticket_id" json:"ticketId"`
    Title           string              `bson:"title" json:"title"`
    Description     string              `bson:"description,omitempty" json:"description,omitempty"`
    Status          string              `bson:"status" json:"status"`
    Priority        string              `bson:"priority" json:"priority"`

    // Relations
    WorkflowID      *primitive.ObjectID `bson:"workflow_id,omitempty" json:"workflowId,omitempty"`
    CurrentPhaseID  string              `bson:"current_phase_id,omitempty" json:"currentPhaseId,omitempty"`

    // Custom fields
    CustomFields    map[string]interface{} `bson:"custom_fields,omitempty" json:"customFields,omitempty"`

    // Timestamps
    CreatedAt       time.Time           `bson:"created_at" json:"createdAt"`
    UpdatedAt       time.Time           `bson:"updated_at" json:"updatedAt"`
}

MongoDB collections are automatically created when first accessed. Indexes are created programmatically in the repository layer.

State Management

The platform uses Zustand for state management:

// Example store configuration
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface TicketStore {
  tickets: Ticket[];
  loading: boolean;
  error: string | null;
  
  fetchTickets: () => Promise<void>;
  createTicket: (data: CreateTicketDto) => Promise<void>;
  updateTicket: (id: string, data: UpdateTicketDto) => Promise<void>;
}

export const useTicketStore = create<TicketStore>()(
  devtools(
    persist(
      (set, get) => ({
        tickets: [],
        loading: false,
        error: null,
        
        fetchTickets: async () => {
          set({ loading: true });
          try {
            const response = await fetch('/api/tickets');
            const data = await response.json();
            set({ tickets: data, loading: false });
          } catch (error) {
            set({ error: error.message, loading: false });
          }
        },
        
        // ... other methods
      }),
      {
        name: 'ticket-storage',
      }
    )
  )
);

Common Tasks

Create widget component:

// src/components/widgets/MyWidget.tsx
export const MyWidget: React.FC<WidgetProps> = ({ data, config }) => {
  return (
    <WidgetContainer>
      {/* Widget content */}
    </WidgetContainer>
  );
};

// src/components/dashboard/widget-library.tsx
import { MyWidget } from '../widgets/MyWidget';

export const widgetLibrary = {
  // ... existing widgets
  'my-widget': {
    component: MyWidget,
    defaultConfig: {
      title: 'My Widget',
      size: { width: 2, height: 2 }
    }
  }
};

Creating a New Page

Create page component:

// src/app/my-page/page.tsx
export default function MyPage() {
  return (
    <PageLayout>
      <h1>My Page</h1>
      {/* Page content */}
    </PageLayout>
  );
}

Add navigation:

// src/components/layout/sidebar.tsx
const navigationItems = [
  // ... existing items
  {
    label: 'My Page',
    href: '/my-page',
    icon: <MyIcon />
  }
];

Testing

Unit Testing

# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

E2E Testing

# Run E2E tests
npm run test:e2e

# Open Cypress
npm run cypress:open

Testing Best Practices

// Example test
import { render, screen, fireEvent } from '@testing-library/react';
import { TicketForm } from '@/components/tickets/ticket-form';

describe('TicketForm', () => {
  it('should create a new ticket', async () => {
    render(<TicketForm />);
    
    // Fill form
    fireEvent.change(screen.getByLabelText('Title'), {
      target: { value: 'Test Ticket' }
    });
    
    // Submit
    fireEvent.click(screen.getByText('Create Ticket'));
    
    // Assert
    await screen.findByText('Ticket created successfully');
  });
});

Deployment

Production Build

# Build web application
cd apps/web
npm run build

# Build documentation
cd ../docs
npm run build

Docker Deployment

# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./
RUN npm ci --production
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t dashboard-app .
docker run -p 3000:3000 dashboard-app

Troubleshooting

Common Issues

Database Connection Error

Error: Can't connect to MySQL database

Solution: Ensure MySQL is running and credentials in .env.local are correct.

Port Already in Use

Error: Port 3000 is already in use

Solution: Kill the process or use a different port:

PORT=3001 npm run dev

Prisma Migration Issues

Error: Migration failed

Solution: Reset database and re-run migrations:

npx prisma migrate reset
npx prisma migrate dev

Next Steps

Architecture Overview - Understand system design
Workflow Management - Learn about workflows
Dashboard Customization - Customize dashboards
API Documentation - Integrate with the API

Getting Help

GitHub Issues: Report bugs or request features
Documentation: You're already here!
Community: Join our Discord server (coming soon)

Happy coding! 🚀

Prerequisites​

Quick Start​

1. Clone the Repository​

2. Install Dependencies​

3. Environment Setup​

Web Application (.env.local)​

4. Database Setup​

MongoDB Setup​

Redis Setup​

5. Start Development Servers​

Project Structure​

Development Workflow​

1. Feature Development​

2. Branch Naming Convention​

3. Commit Message Format​

Configuration Deep Dive​

Database Configuration​

State Management​

Common Tasks​

Adding a New Widget​

Creating a New Page​

Testing​

Unit Testing​

E2E Testing​

Testing Best Practices​

Deployment​

Production Build​

Docker Deployment​

Troubleshooting​

Common Issues​

Database Connection Error​

Port Already in Use​

Prisma Migration Issues​

Next Steps​

Getting Help​