Neo platform - First Version
This commit is contained in:
Francisco Gaona
345
GETTING_STARTED.md
Normal file
345
GETTING_STARTED.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user