neo/GETTING_STARTED.md

Neo Platform - Getting Started Guide

Quick Start

Prerequisites

• Docker 20.10+
• Docker Compose 2.0+
• Node.js 22+ (for local development without Docker)

Option 1: Using Setup Script (Recommended)

# Make setup script executable
chmod +x setup.sh

# Run setup
./setup.sh

This will:

1. Build all Docker containers
2. Start all services
3. Run database migrations
4. Generate Prisma client

Option 2: Manual Setup

# Navigate to infrastructure directory
cd infra

# Build and start containers
docker-compose up --build -d

# Wait for database to be ready (about 10 seconds)
sleep 10

# Run migrations
docker-compose exec api npx prisma migrate dev --name init

# Generate Prisma client
docker-compose exec api npx prisma generate

Access the Application

• Frontend (Web UI): http://localhost:3001
• Backend API: http://localhost:3000/api
• Database: localhost:3306
  • User: platform
  • Password: platform
  • Database: platform
• Redis: localhost:6379

Initial Setup

1. Create a Tenant

Since this is a multi-tenant platform, you need to create a tenant first. Use a tool like cURL or Postman:

# Create a tenant directly in the database
docker-compose exec db mysql -uplatform -pplatform platform -e "
INSERT INTO tenants (id, name, slug, isActive, createdAt, updatedAt) 
VALUES (UUID(), 'Demo Tenant', 'demo', 1, NOW(), NOW());
"

# Get the tenant ID
docker-compose exec db mysql -uplatform -pplatform platform -e "
SELECT id, slug FROM tenants WHERE slug='demo';
"

Save the tenant ID for the next steps.

2. Register a User

# Replace TENANT_ID with the actual tenant ID from step 1
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: TENANT_ID" \
  -d '{
    "email": "admin@demo.com",
    "password": "password123",
    "firstName": "Admin",
    "lastName": "User"
  }'

3. Login

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: TENANT_ID" \
  -d '{
    "email": "admin@demo.com",
    "password": "password123"
  }'

Save the access_token from the response.

4. Configure Frontend

In your browser:

1. Open http://localhost:3001
2. Open Developer Tools (F12)
3. Go to Console and run:

localStorage.setItem('tenantId', 'YOUR_TENANT_ID');
localStorage.setItem('token', 'YOUR_ACCESS_TOKEN');

Reload the page and you should be able to access the platform!

Creating Your First App

1. Create an Object Definition

curl -X POST http://localhost:3000/api/setup/objects \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "apiName": "Project",
    "label": "Project",
    "pluralLabel": "Projects",
    "description": "Project management object"
  }'

2. Create an Application

curl -X POST http://localhost:3000/api/setup/apps \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "slug": "project-mgmt",
    "label": "Project Management",
    "description": "Manage your projects"
  }'

3. Create a Page in the App

curl -X POST http://localhost:3000/api/setup/apps/project-mgmt/pages \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "slug": "projects",
    "label": "Projects",
    "type": "list",
    "objectApiName": "Project",
    "sortOrder": 0
  }'

4. Access Your App

Navigate to: http://localhost:3001/app/project-mgmt/projects

Development Workflow

View Logs

cd infra

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api
docker-compose logs -f web

Restart Services

cd infra
docker-compose restart

Stop Services

cd infra
docker-compose down

Run Prisma Studio (Database GUI)

cd infra
docker-compose exec api npx prisma studio

Access at: http://localhost:5555

Create a New Migration

# After modifying prisma/schema.prisma
cd infra
docker-compose exec api npx prisma migrate dev --name your_migration_name

Reset Database

cd infra
docker-compose exec api npx prisma migrate reset

API Endpoints

Authentication

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login and get JWT token

Runtime APIs (for end users)

• GET /api/runtime/apps - List apps
• GET /api/runtime/apps/:appSlug - Get app with pages
• GET /api/runtime/apps/:appSlug/pages/:pageSlug - Get page metadata
• GET /api/runtime/objects/:objectApiName/records - List records
• GET /api/runtime/objects/:objectApiName/records/:id - Get record
• POST /api/runtime/objects/:objectApiName/records - Create record
• PUT /api/runtime/objects/:objectApiName/records/:id - Update record
• DELETE /api/runtime/objects/:objectApiName/records/:id - Delete record

Setup APIs (for admins)

• GET /api/setup/objects - List object definitions
• GET /api/setup/objects/:objectApiName - Get object definition
• POST /api/setup/objects - Create custom object
• POST /api/setup/objects/:objectApiName/fields - Add field to object
• GET /api/setup/apps - List apps
• GET /api/setup/apps/:appSlug - Get app
• POST /api/setup/apps - Create app
• PUT /api/setup/apps/:appSlug - Update app
• POST /api/setup/apps/:appSlug/pages - Create page
• PUT /api/setup/apps/:appSlug/pages/:pageSlug - Update page

Frontend Routes

• / - Home page
• /setup/apps - App builder (list all apps)
• /setup/apps/:slug - App detail (manage pages)
• /setup/objects - Object builder (list all objects)
• /setup/objects/:apiName - Object detail (manage fields)
• /app/:appSlug/:pageSlug - Runtime page view
• /app/:appSlug/:pageSlug/:recordId - Runtime record detail

Project Structure

neo/
├── backend/              # NestJS API
│   ├── src/
│   │   ├── auth/        # JWT authentication
│   │   ├── tenant/      # Multi-tenancy middleware
│   │   ├── rbac/        # Roles & permissions
│   │   ├── object/      # Object & field management
│   │   ├── app-builder/ # App & page management
│   │   └── prisma/      # Prisma service
│   └── prisma/
│       └── schema.prisma # Database schema
├── frontend/            # Nuxt 3 web app
│   ├── pages/          # Vue pages/routes
│   ├── composables/    # Reusable composition functions
│   └── assets/         # CSS & static files
├── infra/
│   └── docker-compose.yml
├── .env.api            # Backend environment variables
├── .env.web            # Frontend environment variables
└── README.md

Troubleshooting

Database Connection Issues

# Check if database is running
docker ps | grep platform-db

# Check database logs
cd infra && docker-compose logs db

API Not Starting

# Check API logs
cd infra && docker-compose logs api

# Rebuild API container
cd infra && docker-compose up --build api

Frontend Not Loading

# Check web logs
cd infra && docker-compose logs web

# Rebuild web container
cd infra && docker-compose up --build web

Port Already in Use

If ports 3000, 3001, 3306, or 6379 are already in use, you can modify the port mappings in infra/docker-compose.yml.

Next Steps

1. Implement Custom Object Runtime Queries: Currently only the Account object has runtime query support. Extend ObjectService to support dynamic queries for custom objects.

2. Add Field-Level Security (FLS): Implement field-level permissions to control which fields users can read/write.

3. Enhance Sharing Rules: Implement more sophisticated record sharing rules beyond simple ownership.

4. Add BullMQ Jobs: Implement background job processing using BullMQ for async operations.

5. Build UI Components: Use radix-vue to build reusable form components, tables, and modals.

6. Add Validation: Implement proper validation using class-validator for all DTOs.

7. Add Tests: Write unit and integration tests for both backend and frontend.

Support

For issues and questions, please refer to the README.md or create an issue in the repository.