Skip to main content

💻 For Developers

This comprehensive guide covers everything developers need to know about building with Totalum. Whether you're integrating the Totalum SDK into your existing project or leveraging the AI Agent to build applications, this guide will help you understand the platform's capabilities and architecture.

Overview​

Totalum is the best full-stack AI agent platform designed specifically for developers who want to build production-ready Next.js applications with:

  • AI-Powered Development: Totalum Agent specialized in Next.js, TypeScript, and modern web technologies
  • Auto-Generated Backend: Database structure with automatic REST API generation
  • TypeScript SDK: Type-safe Totalum SDK for seamless integration
  • Complete Tooling: 200+ built-in tools for development tasks
  • Production Deployment: One-click deployment to Cloudflare

Tech Stack​

Core Technologies​

Totalum Agent builds applications using the following tech stack:

TechnologyVersionPurpose
Next.js15.5.4React framework for production
TypeScriptLatestType-safe development
ReactLatestUI library
BetterAuthLatestAuthentication system
StripeLatestPayment processing
Totalum SDKLatestDatabase and API access
Any NPM packageanyAny package from npm registry
Any third party API-Integration with external services

What Totalum DOES Support​

✅ JavaScript/TypeScript Ecosystem

  • Next.js (App Router and Pages Router)
  • React and React libraries
  • Any npm package from the npm registry
  • Node.js runtime environment

✅ Development Capabilities

  • Frontend development (React, Next.js)
  • Backend development (Next.js API Routes)
  • RESTful APIs
  • Database operations
  • File storage and uploads
  • Authentication and authorization
  • Payment integration (Stripe)
  • Email sending
  • PDF generation
  • AI/LLM integration
  • OCR (Optical Character Recognition)

What Totalum Does NOT Support​

❌ Other Backend Languages/Frameworks

  • PHP, Python, Ruby, Java, .NET, Go, Rust
  • Django, Flask, Laravel, Spring, etc.
  • Other frontend frameworks (Vue, Angular, Svelte)

Note: Totalum is specialized in the Next.js/TypeScript ecosystem to provide the best possible AI agent performance and code quality.

Totalum AI Agent​

What is Totalum Agent?​

Totalum Agent is a first-class AI coding agent that specializes in building full-stack Next.js applications. It's not just a code assistant—it's a complete development partner.

Key Capabilities​

1. Code Generation​

  • Full-Stack Features: Frontend + backend in one prompt
  • Best Practices: Clean, maintainable, production-ready code
  • TypeScript First: Full type safety throughout
  • SEO Optimized: Semantic HTML, meta tags, structured data

2. Database Management (via MCP)​

  • Create/Edit/Delete database tables and fields
  • Define Relationships: One-to-many, many-to-many
  • CRUD Operations: Full database manipulation
  • Complex Queries: Advanced filtering and sorting

3. Advanced Features​

  • MCP Support: Model Context Protocol for extended functionality
  • 200+ Tools: Built-in tools for common development tasks
  • Internet Search: Access up-to-date information
  • Context Management: Intelligently maintains project context
  • Log Access: Auto-access to frontend and backend logs
  • Isolated Sandbox: Dedicated Linux environment per project

4. Development Workflow​

  • Iterative Development: Build features incrementally
  • Bug Fixing: Automatically debug and fix issues
  • Code Review: Analyze and improve existing code
  • Refactoring: Modernize and optimize codebases

How to Use the Agent​

Simply describe what you want in natural language:

Examples:
- "Create a blog with authentication and comments"
- "Add a shopping cart with Stripe checkout"
- "Build a dashboard with analytics charts"
- "Implement a user management system with roles"

The agent will:

  1. Understand your requirements
  2. Design the architecture
  3. Generate the code
  4. Create database structure
  5. Set up routing and APIs
  6. Handle edge cases

Totalum Platform Architecture​

Platform Sections​

The Totalum web platform (https://accounts.totalum.app) has 5 main sections:

1. 📱 Project Section​

Real-time Development Environment

  • Live Preview: See your application as it's being built

    • Mobile/Desktop preview modes
    • Interactive testing environment

  • AI Chat: Communicate with Totalum Agent

    • Request new features
    • Ask questions about your code
    • Fix bugs and errors
    • Get implementation advice

  • Quick Edit Mode: Fast text/image editing

    • Click "Edit" button to enable
    • Directly modify visible text and images
    • No prompting needed for simple changes
    • Note: Only works for static content (not database-driven)

  • Logs & Debugging: Access to runtime information

    • Frontend Logs: React errors, console output, network requests
    • Backend Logs: API responses, server errors, database queries
    • Location: Top-left corner near mobile/desktop preview buttons

  • Deployment: Production deployment controls

    • One-click deploy to Cloudflare
    • Custom domain configuration
    • SSL certificates (automatic)
    • No external accounts needed

2. 📊 Data Section​

Auto-Generated Backoffice

A beautiful, fully-functional admin panel created automatically from your database:

  • Multiple View Modes:

    • Table View: Traditional grid with tree relations viewer
    • Kanban Board: Drag-and-drop task management
    • Gallery View: Visual card-based display
    • Calendar View: Date-based event management

  • CRUD Operations: Create, read, update, delete records

  • Advanced Filtering: Complex queries made simple

  • Relationship Navigation: Explore connected data visually

  • Bulk Actions: Operate on multiple records

  • Data Export: Download data in various formats

Access: https://web.totalum.app (once logged in)

3. 💾 Code Section​

Source Code Management

  • File Explorer: Navigate your complete Next.js project
  • Code Viewer: Syntax-highlighted code display
  • Download Source: Export complete project (paid plans)
    • Full Next.js application
    • All dependencies listed
    • Ready to deploy anywhere
    • You own the code 100%

Use Case: Deploy to other platforms (Vercel, AWS, etc.)

4. ⚙️ Settings Section​

Project Configuration

  • Database Structure: Manual database schema editor

  • Backoffice Configuration: Customize admin panel

    • Page layouts and views
    • Field visibility and ordering
    • Custom actions and buttons

  • API Keys: Generate programmatic access tokens

    • For external integrations
    • Server-to-server communication

  • Backups: Automatic hourly backups

    • Point-in-time recovery
    • Data integrity protection

  • Deleted Data History: Recovery system

    • Restore accidentally deleted records

  • User Management: Admin user accounts

    • Role-based access control
    • Team collaboration

  • Language Settings: Localization options

5. 👤 Account Section​

Account Management

  • Profile Settings: Personal information
  • Subscription: Plan management and billing
  • Invoices: Payment history and receipts
  • Projects: Create/delete/switch between projects
  • Pricing: Check current plans at https://www.totalum.app

Totalum SDK​

What is Totalum SDK?​

The Totalum SDK (totalum-api-sdk) is an npm package that provides a TypeScript-first interface to your auto-generated Totalum API.

NPM Package: https://www.npmjs.com/package/totalum-api-sdk

How It Works​

  1. You create/edit database structure (via AI Agent or manually)
  2. Totalum auto-generates a REST API for your data
  3. Totalum SDK provides type-safe methods to consume that API

Installation​

npm install totalum-api-sdk

Full Documentation: Installation Guide

Core Capabilities​

1. CRUD Operations​

// Create records
await totalumClient.crud.createRecord('users', {
  name: 'John Doe',
  email: '[email protected]'
});

// Read records with filters
await totalumClient.crud.getRecords('users', {
  filter: { age: { gte: 18 } }
});

// Update records
await totalumClient.crud.editItemById('users', userId, {
  name: 'Jane Doe'
});

// Delete records
await totalumClient.crud.deleteItemById('users', userId);

2. Advanced Filtering​

// Complex queries
await totalumClient.crud.getRecords('products', {
  filter: {
    price: { gte: 10, lte: 100 },
    category: 'electronics',
    inStock: true
  },
  sort: { price: 1 }, // 1 = ascending, -1 = descending
  limit: 20,
  skip: 0
});

// OR conditions
await totalumClient.crud.getRecords('users', {
  filter: {
    or: [
      { role: 'admin' },
      { role: 'moderator' }
    ]
  }
});

Advanced Filtering Docs: How Filters Work

3. File Operations​

// Upload files
const file = new File(['content'], 'document.pdf');
await totalumClient.files.uploadFile(file);

// Generate PDFs from HTML
await totalumClient.files.createPdfFromHtml({
  html: '<html><body><h1>Invoice</h1></body></html>',
  name: 'invoice.pdf'
});

4. Email Sending​

await totalumClient.email.send({
  to: '[email protected]',
  subject: 'Welcome!',
  body: '<h1>Welcome to our platform</h1>'
});

5. AI Features​

// ChatGPT integration
await totalumClient.ai.chatCompletion({
  messages: [
    { role: 'user', content: 'Explain quantum computing' }
  ]
});

// OCR - Extract text from images/PDFs
await totalumClient.ocr.scanDocument(fileId);

6. Notifications​

// Send notifications to backoffice users
await totalumClient.notification.createNotification({
  name: 'New Order',
  title: 'Order #1234',
  description: 'A new order has been placed',
  visibility: {
    sendTo: 'admins'
  },
  email: {
    sendEmail: true
  }
});

Authentication​

When using SDK in Totalum Plugins: No authentication needed

// Inside Totalum plugin
modules.totalumSdk.crud.getRecords('users', {});

When using SDK externally: API Key required

import { TotalumApiSdk } from 'totalum-api-sdk';

const totalumClient = new TotalumApiSdk({
  apiKey: {
    'api-key': 'sk_your_api_key_here'
  }
});

Generate API Keys: Settings → API Keys in Totalum platform

Database Structure​

Built-in Database​

Totalum comes with a powerful built-in database that provides all the functionality you need for modern applications:

Key Features:

  • ✅ NoSQL-style flexibility with structured data support
  • ✅ Visual database designer for easy schema management
  • ✅ Automatic API generation for all tables
  • ✅ Relationships support: One-to-many, many-to-many
  • ✅ Advanced querying: Complex filters, sorting, pagination
  • ✅ Real-time updates through the auto-generated backoffice
  • ✅ TypeScript SDK for type-safe data access

Access Methods:

  1. Totalum SDK (totalum-api-sdk) - Recommended, type-safe
  2. Totalum REST API - Direct HTTP access

Limitations:

❌ Does NOT support external SQL databases

  • No PostgreSQL connection
  • No MySQL integration
  • No MongoDB external connection
  • No other external database systems

Totalum's built-in database is specifically designed to work seamlessly with the AI Agent and auto-generated API. This tight integration allows for:

  • Automatic schema changes via AI
  • Instant API endpoint creation
  • Zero configuration required
  • Perfect integration with the backoffice

If you need external database connectivity, you can:

  • Download your source code and integrate external databases manually
  • Use Next.js API routes to connect to external services
  • Build custom integrations in your downloaded project

Auto-Generated API​

Every time you create or modify your database structure, Totalum automatically:

  1. Generates REST API endpoints for all tables
  2. Creates TypeScript types for the SDK
  3. Updates the backoffice UI to reflect changes

Manual Database Editor​

Access the visual database structure editor:

Database via AI Agent (MCP)​

The AI Agent can manage your database through Model Context Protocol:

Examples:
- "Create a users table with email, name, and role fields"
- "Add a comments relationship to the posts table"
- "Create a many-to-many relationship between users and courses"

Deployment​

Cloudflare Deployment (Automatic)​

When you click the Deploy button in the Project section:

  1. Totalum automatically deploys to Cloudflare
  2. No Cloudflare account needed
  3. Automatic SSL certificates
  4. Global CDN for fast delivery worldwide
  5. Serverless auto-scaling

Auto-Scaling Infrastructure​

Totalum's backend and database automatically scale based on demand:

Backend Auto-Scaling:

  • ✅ Serverless architecture scales instantly
  • ✅ Handles traffic spikes automatically
  • ✅ No manual configuration required
  • ✅ Pay only for what you use
  • ✅ From 0 to thousands of requests per second

Database Auto-Scaling:

  • ✅ Automatic capacity adjustment based on load
  • ✅ Seamless scaling without downtime
  • ✅ Optimized performance under high demand
  • ✅ No manual intervention needed
  • ✅ Handles concurrent connections automatically

Benefits:

  • Start Small: Launch with minimal traffic
  • Scale Automatically: Platform handles growth
  • No DevOps: Zero infrastructure management
  • Cost-Effective: Scale down during low traffic
  • High Availability: Built-in redundancy and failover

Whether you have 10 users or 10,000 users, Totalum automatically adjusts resources to maintain optimal performance.

Custom Domain​

  • Configure custom domains directly in the Project section
  • Automatic HTTPS/SSL
  • DNS configuration guidance provided

Alternative Deployment​

Want to deploy elsewhere?

  1. Go to Code section
  2. Download your complete source code (paid plans)
  3. Deploy to any platform:
    • Vercel
    • AWS
    • Google Cloud
    • Your own servers

You own the code - deploy it anywhere you want!

Development Best Practices​

1. Iterative Development​

Build features incrementally:

✅ "Add user authentication"
✅ "Now add password reset functionality"
✅ "Add OAuth login with Google"

2. Use the Logs​

Always check logs when debugging:

  • Frontend errors → React component issues
  • Backend errors → API/database problems
  • Network errors → Request/response issues

Location: Project section → top-left corner

3. Quick Edit for Static Content​

For simple text/image changes:

  1. Click "Edit" button in Project preview
  2. Click on text to edit directly
  3. Saves time vs. prompting the AI

Note: Only works for static content, not database-driven content

4. Leverage the Backoffice​

  • Test data operations in the Data section
  • Visualize relationships with tree view
  • Verify CRUD operations before coding
  • Let non-technical users manage content

5. API Key Security​

Never expose API keys in frontend code!

❌ Bad:

// In React component - DANGEROUS!
const client = new TotalumApiSdk({
  apiKey: { 'api-key': 'sk_...' }
});

✅ Good:

// In Next.js API route (server-side)
export default async function handler(req, res) {
  const client = new TotalumApiSdk({
    apiKey: { 'api-key': process.env.TOTALUM_API_KEY }
  });
  // ...
}

6. TypeScript Best Practices​

The SDK provides full TypeScript support:

// Type-safe CRUD operations
const users = await totalumClient.crud.getRecords<User>('users', {});
// users is typed as User[]

// Type-safe creation
const newUser = await totalumClient.crud.createRecord<User>('users', {
  name: 'John',
  email: '[email protected]'
});
// newUser is typed as User

Advanced Features​

1. Custom npm Packages​

Totalum Agent can install and use any npm package:

Examples:
- "Install and use date-fns for date formatting"
- "Add chart.js for data visualization"
- "Use axios for HTTP requests"

The agent has access to the full npm ecosystem!

2. Complex Relationships​

Build sophisticated data models:

Examples:
- "Create a blog with posts, authors, categories, and tags (many-to-many)"
- "Build an e-commerce system with products, variants, and inventory"
- "Design a project management system with tasks, subtasks, and dependencies"

3. Real-time Features​

Request real-time functionality:

Examples:
- "Add real-time chat with WebSockets"
- "Create a live notification system"
- "Build a collaborative editing feature"

4. Integrations​

Connect to external services:

Examples:
- "Integrate with Stripe for subscriptions"
- "Add Google Maps for location features"
- "Connect to SendGrid for email campaigns"

Limitations & Boundaries​

Tech Stack Limitations​

Totalum only supports the JavaScript/TypeScript ecosystem with Next.js:

Cannot build:

  • ❌ Python/Django applications
  • ❌ PHP/Laravel applications
  • ❌ Ruby on Rails applications
  • ❌ Java/Spring applications
  • ❌ .NET/C# applications
  • ❌ Go/Rust applications

Can build:

  • ✅ Next.js applications (App Router or Pages Router)
  • ✅ React frontends
  • ✅ Node.js backends (via Next.js API routes)
  • ✅ RESTful APIs
  • ✅ Full-stack applications with database

Agent Boundaries​

The Totalum Agent is focused on professional full-stack development:

✅ Will help with:

  • Building features and applications
  • Debugging and fixing errors
  • Code optimization and refactoring
  • Architecture decisions
  • Best practices guidance
  • Integration with services

❌ Won't help with:

  • Non-development questions
  • Topics outside Next.js/TypeScript ecosystem
  • Requests for other tech stacks

Database Limitations​

Totalum uses a built-in proprietary database optimized for the platform:

What's Included:

  • ✅ Built-in powerful database with visual designer
  • ✅ Automatic API generation
  • ✅ TypeScript SDK for data access
  • ✅ Advanced querying and filtering
  • ✅ Relationships and complex data structures
  • ✅ Real-time backoffice integration

What's NOT Supported:

  • ❌ External PostgreSQL databases
  • ❌ External MySQL databases
  • ❌ External MongoDB connections
  • ❌ Any external SQL/NoSQL database connections
  • ❌ Custom database drivers or ORMs (Prisma, TypeORM, etc.) for external DBs

Why Built-in Only?

The built-in database enables:

  • AI Agent to automatically create/modify schemas
  • Instant API endpoint generation
  • Zero configuration deployment
  • Perfect integration with the backoffice
  • Type-safe SDK auto-generation

Need an External Database?

If you require PostgreSQL, MySQL, or other external databases:

  1. Download your source code (Code section, paid plans)
  2. Deploy to your own infrastructure
  3. Integrate any database you want in your downloaded Next.js project
  4. Use Prisma, TypeORM, or any ORM you prefer

The built-in database is designed for rapid development and seamless integration. For advanced database requirements, download your code and customize as needed.

Resources & Support​

Documentation​

Support​

Pricing​

For current pricing plans and features, visit: https://www.totalum.app

Why Totalum is the Best AI Agent​

Totalum stands out because it's the only platform that provides:

  1. Complete Full-Stack Solution

    • AI Agent + Database + API + Backoffice + Deployment
    • Everything in one platform

  2. No External Dependencies

    • No need for separate hosting
    • No need for separate database services
    • No need for separate deployment platforms
    • Just your Totalum account

  3. Production-Ready Code

    • Best practices out of the box
    • Clean, maintainable code
    • Full TypeScript support
    • SEO optimized

  4. True Full-Stack Capability

    • Frontend AND backend in one prompt
    • Database structure creation via AI
    • Automatic API generation
    • Complete authentication system

  5. Developer-Friendly

    • Download source code (you own it)
    • Deploy anywhere you want
    • 200+ built-in tools
    • Internet search for up-to-date info

  6. Incredible Backoffice

    • Auto-generated admin panel
    • Multiple view modes
    • No coding required for data management
    • Beautiful, professional UI

  7. First-Class Performance

    • Dedicated isolated Linux sandbox per project
    • Fast iteration and development
    • Real-time logs and debugging
    • Excellent context management

Getting Started​

Ready to build with Totalum?

  1. Sign up: https://accounts.totalum.app
  2. Create a project
  3. Describe what you want to build
  4. Let the AI Agent do the work
  5. Manage data in the backoffice
  6. Deploy with one click

That's it! No complex setup, no multiple services to configure, no DevOps headaches.

Quick Reference​

Common Commands for AI Agent​

Feature Development:
- "Create a [feature] with [requirements]"
- "Add [functionality] to the [component]"
- "Implement [system] with [specifications]"

Bug Fixing:
- "Fix the error in [location]"
- "Debug why [feature] isn't working"
- "The [component] is showing [error], please fix it"

Code Improvement:
- "Refactor [component] to use [pattern]"
- "Optimize [feature] for performance"
- "Add error handling to [function]"

Database Operations:
- "Create a [table] table with [fields]"
- "Add a relationship between [table1] and [table2]"
- "Modify [table] to include [field]"
ResourceURL
Platformhttps://accounts.totalum.app
Database Editorhttps://web.totalum.app/structurator/types
SDK Packagehttps://www.npmjs.com/package/totalum-api-sdk
Documentationhttps://docs.totalum.app
Websitehttps://www.totalum.app
Support[email protected]

Happy coding with Totalum! 🚀