# 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)

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
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:

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

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

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

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

```bash
cd infra

# All services
docker-compose logs -f

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

### Restart Services

```bash
cd infra
docker-compose restart
```

### Stop Services

```bash
cd infra
docker-compose down
```

### Run Prisma Studio (Database GUI)

```bash
cd infra
docker-compose exec api npx prisma studio
```

Access at: http://localhost:5555

### Create a New Migration

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

### Reset Database

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

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

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

### API Not Starting

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

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

### Frontend Not Loading

```bash
# 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.