Integration Guide

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.

Frontend Framework

Use Next.js as the frontend framework for all applications.

Backend Framework

If your application requires backend APIs, use Node.js or Express.js.

Database Configuration

All applications use MongoDB with a specific collection naming convention to prevent conflicts.

Collection Naming Pattern:

app_{appName}_{tableName}

Database Connection Setup:

Local Development
Cloud Deployment

const mongoUri = process.env.MONGODB_URI;

const mongoUri = `mongodb://${process.env.DB_USERNAME}:${process.env.DB_PASSWORD}@${process.env.DB_HOST}`;

Authentication Requirements

Access to any application requires user authentication through Weam. Unauthenticated users must see a 404 page.

Check User Login Status

Verify authentication before rendering any content.

Handle Unauthenticated Users

Return a 404 page if user is not logged in.

Use IronSession

Leverage the pre-configured ironSession package for session handling.

Implementation Example:

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

Always include user context and company identification when storing data to maintain proper access controls.

Required Data Structure:

{
  "user": {
    "id": session.user.id,
    "email": session.user.email
  },
  "companyId": session.user.companyId,
  // Your application-specific data
  ...appData
}

Theming Integration

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:

Environment Variables

NEXT_PUBLIC_API_BASE_PATH="/your-app-name"

Next.js Configuration

// 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`

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.

Update and Install NGINX

sudo apt update
sudo apt install nginx -y

Create NGINX Configuration

sudo nano /etc/nginx/sites-available/yourapp

Show Complete NGINX Configuration

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;
    }
}

Enable Site and Test Configuration

sudo ln -s /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Install SSL Certificate Tools

sudo apt install certbot python3-certbot-nginx -y

Generate SSL Certificate

sudo certbot --nginx -d yourexampledomain.com

Final Access URL:

https://yourexampledomain.com

Development Workflow

Project Setup

Create your Next.js application following the requirements above

Authentication Integration

Implement user authentication checks using ironSession

Database Configuration

Configure MongoDB with proper collection naming convention

Theme Application

Apply Weam’s visual theme and component patterns

Routing Setup

Configure base path and API routes with proper prefixes

Sidebar Integration

Add application to sidebar configuration file

Production Deployment

Configure nginx proxy rules and SSL certificates

Project Structure

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

Required Variables
Development Setup

# Application Configuration
NEXT_PUBLIC_API_BASE_PATH="/your-app-name"
MONGODB_URI=your-mongodb-connection-string

# Development URLs
DB_HOST=localhost
DB_USERNAME=your-username
DB_PASSWORD=your-password

This integration method ensures your custom applications work within Weam’s existing architecture while maintaining security and consistency.

Common Functions

App Development

Workflows

Integration Guide

Core Requirements

Frontend Framework

Backend Framework

Database Configuration

Authentication Requirements

Data Storage Convention

Theming Integration

Routing & Deployment

Base Path Configuration

Sidebar Integration

NGINX Setup Guide

Development Workflow

Project Structure

Environment Configuration

​Core Requirements

Frontend Framework

Backend Framework

​Database Configuration

​Authentication Requirements

​Data Storage Convention

​Theming Integration

​Routing & Deployment

​Base Path Configuration

​Sidebar Integration

​NGINX Setup Guide

​Development Workflow

​Project Structure

​Environment Configuration

Core Requirements

Database Configuration

Authentication Requirements

Data Storage Convention

Theming Integration

Routing & Deployment

Base Path Configuration

Sidebar Integration

NGINX Setup Guide

Development Workflow

Project Structure

Environment Configuration