> ## Documentation Index
> Fetch the complete documentation index at: https://opensource.weam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

> Technical guide for building and integrating custom applications into Weam AI

This guide covers the technical requirements for building and integrating custom applications into the Weam AI platform.

## Core Requirements

Follow these 10 essential standards to ensure your application integrates properly with Weam AI.

> [card] Frontend Framework
>
> Use **Next.js** as the frontend framework for all applications.

> [card] Backend Framework
>
> If your application requires backend APIs, use **Node.js** or **Express.js**.

### Database Configuration

> [!WARNING]
>
> All applications use MongoDB with a specific collection naming convention to prevent conflicts.

**Collection Naming Pattern:**

```
app_{appName}_{tableName}
```

**Database Connection Setup:**

> [tab] Local Development
>
> ```javascript theme={null}
> const mongoUri = process.env.MONGODB_URI;
> ```

> [tab] Cloud Deployment
>
> ```javascript theme={null}
> const mongoUri = `mongodb://${process.env.DB_USERNAME}:${process.env.DB_PASSWORD}@${process.env.DB_HOST}`;
> ```

### Authentication Requirements

> [!NOTE]
>
> Access to any application requires user authentication through Weam. Unauthenticated users must see a 404 page.

**1. Check User Login Status**

Verify authentication before rendering any content.

**2. Handle Unauthenticated Users**

Return a 404 page if user is not logged in.

**3. Use IronSession**

Leverage the pre-configured ironSession package for session handling.

**Implementation Example:**

```javascript Session Check theme={null}
import { getIronSession } from 'iron-session';
import { sessionOptions } from '../lib/session';

export async function getServerSideProps({ req, res }) {
  const session = await getIronSession(req, res, sessionOptions);
  
  if (!session.user) {
    return {
      notFound: true, // Returns 404 for unauthenticated users
    };
  }
  
  return {
    props: { user: session.user }
  };
}
```

### Data Storage Convention

> [!TIP]
>
> Always include user context and company identification when storing data to maintain proper access controls.

**Required Data Structure:**

```javascript theme={null}
{
  "user": {
    "id": session.user.id,
    "email": session.user.email
  },
  "companyId": session.user.companyId,
  // Your application-specific data
  ...appData
}
```

### Theming Integration

> [!NOTE]
>
> Applications should match the existing Weam theme for consistent user experience. Use the same CSS variables and component patterns as the main platform.

## Routing & Deployment

### Base Path Configuration

All applications run behind nginx and require proper path configuration:

> [accordion] Environment Variables
>
> ```bash theme={null}
> NEXT_PUBLIC_API_BASE_PATH="/your-app-name"
> ```

> [accordion] Next.js Configuration
>
> ```javascript theme={null}
> // next.config.js
> module.exports = {
>   basePath: process.env.NEXT_PUBLIC_API_BASE_PATH || '',
>   assetPrefix: process.env.NEXT_PUBLIC_API_BASE_PATH || '',
> }
> ```

**URL Structure Examples:**

| Route Type | Example URL |
| - | - |
| **Page** | `yourexampledomain.com/your-app-name/dashboard` |
| **API** | `yourexampledomain.com/your-app-name/api/message` |

### Sidebar Integration

> [!TIP]
>
> Make your application discoverable by adding it to the sidebar navigation.

**Configuration File:** `src/seeders/superSolution.json`

Add a new object following the structure of existing applications. This ensures your application appears automatically in the sidebar navigation.

## NGINX Setup Guide

Complete server configuration for production deployment.

**1. Update and Install NGINX**

```bash theme={null}
sudo apt update
sudo apt install nginx -y
```

**2. Create NGINX Configuration**

```bash theme={null}
sudo nano /etc/nginx/sites-available/yourapp
```

**Complete NGINX Configuration**

```nginx theme={null}
server {
    listen 80;
    server_name yourexampledomain.com;
    
    # Main App
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # Node API
    location /napi/ {
        proxy_pass http://localhost:4050/napi/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
    }
    
    # MinIO
    location /minio/ {
        proxy_pass http://localhost:9000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # Followup App (port 4000)
    location /followup/ {
        proxy_pass http://localhost:4000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # ai-doc (port 3002)
    location = /ai-doc {
        proxy_pass http://localhost:3002/ai-doc;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /ai-doc/ {
        proxy_pass http://localhost:3002/ai-doc/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # Your custom app configuration
    location /your-app-name/ {
        proxy_pass http://localhost:YOUR_PORT/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**3. Enable Site and Test Configuration**

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

**4. Install SSL Certificate Tools**

```bash theme={null}
sudo apt install certbot python3-certbot-nginx -y
```

**5. Generate SSL Certificate**

```bash theme={null}
sudo certbot --nginx -d yourexampledomain.com
```

**Final Access URL:**

```
https://yourexampledomain.com
```

## Development Workflow

**1. Project Setup**

Create your Next.js application following the requirements above

**2. Authentication Integration**

Implement user authentication checks using ironSession

**3. Database Configuration**

Configure MongoDB with proper collection naming convention

**4. Theme Application**

Apply Weam's visual theme and component patterns

**5. Routing Setup**

Configure base path and API routes with proper prefixes

**6. Sidebar Integration**

Add application to sidebar configuration file

**7. Production Deployment**

Configure nginx proxy rules and SSL certificates

## Project Structure

> [accordion] Recommended File Structure
>
> ```
> your-app/
> ├── pages/
> │   ├── api/
> │   │   └── message.js
> │   ├── _app.js
> │   └── dashboard.js
> ├── lib/
> │   ├── mongodb.js
> │   └── session.js
> ├── components/
> ├── styles/
> └── next.config.js
> ```

## Environment Configuration

> [tab] Required Variables
>
> ```bash theme={null}
> # Application Configuration
> NEXT_PUBLIC_API_BASE_PATH="/your-app-name"
> MONGODB_URI=your-mongodb-connection-string
> ```

> [tab] Development Setup
>
> ```bash theme={null}
> # Development URLs
> DB_HOST=localhost
> DB_USERNAME=your-username
> DB_PASSWORD=your-password
> ```

> [!NOTE]
>
> This integration method ensures your custom applications work within Weam's existing architecture while maintaining security and consistency.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.