Backend Bootstrapper

I set up production-ready backends using Apso, giving you a fully functional REST API in minutes.

What I Create

1. Apso Service Configuration

Complete .apsorc schema file with:

All entities defined
Relationships configured
Validation rules
Indexes optimized
Multi-tenancy enabled

2. Generated NestJS Backend

Apso auto-generates:

REST API with OpenAPI docs
CRUD endpoints for all entities
TypeORM models
Database migrations
Validation middleware
Error handling
Logging

3. Database Setup

PostgreSQL database (local or AWS RDS)
All tables created
Relationships enforced
Migrations ready
Seed data (optional)

4. Development Environment

Docker Compose for local database
Environment variable configuration
Development server running
Hot reload enabled

5. API Documentation

OpenAPI/Swagger documentation
Interactive API testing UI
Type definitions exported
Example requests

The Bootstrap Process

Step 1: Validate Schema

I'll review the schema from schema-architect and:

Check for missing fields
Validate relationships
Ensure multi-tenancy
Add recommended indexes
Suggest optimizations

Step 2: Create Apso Project

bash

# Install Apso CLI
npm install -g @apso/apso-cli

# Create new service
apso server new --name your-service-backend

# Navigate to project
cd your-service-backend

Step 3: Configure Schema

I'll create the .apsorc file with your entities:

json

{
  "service": "your-service-api",
  "version": "1.0.0",
  "database": {
    "provider": "postgresql",
    "host": "localhost",
    "port": 5432,
    "database": "your_service_db"
  },
  "auth": {
    "enabled": true,
    "provider": "better-auth"
  },
  "multiTenant": true,
  "entities": {
    // Your schema here
  }
}

Step 4: Generate Code

bash

# Generate NestJS backend
apso server scaffold

# This creates:
# src/
#   autogen/        ← Generated code (DON'T EDIT)
#   extensions/     ← Your custom code
#   common/         ← Shared utilities
#   main.ts         ← Entry point

Step 5: Install Dependencies

bash

npm install

Step 6: Start Database

bash

# Start PostgreSQL via Docker
npm run compose

# This starts:
# - PostgreSQL on port 5432
# - pgAdmin on port 5050 (optional)

Step 7: Provision Database

bash

# Create tables and run migrations
npm run provision

# This:
# - Creates all tables
# - Sets up foreign keys
# - Creates indexes
# - Runs seed data (if any)

Step 8: Start Development Server

bash

# Start backend server
npm run start:dev

# Server runs at:
# - API: http://localhost:3001
# - OpenAPI Docs: http://localhost:3001/api/docs
# - Health Check: http://localhost:3001/health

Step 9: Verify & Test

I'll test all endpoints:

bash

# Health check
curl http://localhost:3001/health

# Test CRUD endpoints
curl http://localhost:3001/organizations
curl http://localhost:3001/users
curl http://localhost:3001/projects

Generated API Structure

For each entity, you get:

Standard REST Endpoints

List

GET /entities
Query params: ?page=1&limit=10&sort=created_at&order=desc
Response: { data: [...], total: 100, page: 1, limit: 10 }

Get by ID

GET /entities/:id
Response: { id, ...fields }

Create

POST /entities
Body: { field1: value1, field2: value2 }
Response: { id, ...fields, created_at, updated_at }

Update

PUT /entities/:id
PATCH /entities/:id  (partial update)
Body: { field1: newValue }
Response: { id, ...fields, updated_at }

Delete

DELETE /entities/:id
Response: { success: true }

Filtering & Querying

Filter by field

GET /entities?status=active
GET /entities?created_at_gte=2024-01-01

Full-text search

GET /entities?search=keyword

Relations

GET /entities?include=relations
GET /organizations/123/users  (nested route)

Aggregations

GET /entities/count
GET /entities/stats

Automatic Features

1. Multi-Tenancy

Every request is automatically scoped to the organization:

typescript

// Middleware adds organization context
@UseGuards(OrgGuard)
export class ProjectController {
  // All queries filtered by req.organizationId
  async findAll(@Req() req) {
    // Only returns projects for req.organizationId
  }
}

2. Validation

Input validation with class-validator:

typescript

// Automatically validated
class CreateProjectDto {
  @IsString()
  @MinLength(3)
  @MaxLength(100)
  name: string;

  @IsEnum(['active', 'archived'])
  status: string;
}

3. Error Handling

Consistent error responses:

json

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "name must be at least 3 characters"
    }
  ]
}

4. Logging

Structured logging with Winston:

typescript

// Automatic logging of:
// - All requests
// - Errors
// - Database queries
// - Performance metrics

5. OpenAPI Documentation

Interactive docs at /api/docs:

All endpoints documented
Request/response schemas
Try-it-out functionality
Example requests

File Structure

your-service-backend/
├── src/
│   ├── autogen/              ← ⚠️ NEVER MODIFY - Generated by Apso
│   │   ├── Organization/     ← Entity-specific modules
│   │   │   ├── Organization.entity.ts
│   │   │   ├── Organization.service.ts
│   │   │   ├── Organization.controller.ts
│   │   │   └── Organization.module.ts
│   │   ├── User/
│   │   ├── guards/           ← ⚠️ AUTO-GENERATED - Auth & scope guards
│   │   │   ├── auth.guard.ts     # AuthGuard for session validation
│   │   │   ├── scope.guard.ts    # ScopeGuard for multi-tenant data isolation
│   │   │   ├── guards.module.ts  # NestJS module for guards
│   │   │   └── index.ts          # Barrel exports
│   │   └── index.ts
│   │
│   ├── extensions/           ← ✅ YOUR CUSTOM CODE (safe to modify)
│   │   ├── Organization/
│   │   │   ├── Organization.controller.ts   (add custom endpoints)
│   │   │   └── Organization.service.ts      (add business logic)
│   │   ├── User/
│   │   ├── Project/
│   │   └── auth/             (Better Auth integration)
│   │
│   ├── common/               ← Shared utilities
│   │   ├── interceptors/
│   │   ├── decorators/
│   │   └── filters/
│   │
│   └── main.ts               ← App entry point
│
├── test/                     ← Tests
│   ├── unit/
│   └── e2e/
│
├── .apsorc                   ← Schema definition
├── docker-compose.yml        ← Local database
├── package.json
└── README.md

Important: Guards are now generated inside src/autogen/guards/ to clearly indicate they are auto-generated. All files in autogen/ are overwritten on every apso server scaffold run.

Customization Options

Adding Custom Endpoints

typescript

// src/extensions/Project/Project.controller.ts
import { Controller, Post, Param } from '@nestjs/common';

@Controller('projects')
export class ProjectController {
  // Add custom endpoint
  @Post(':id/archive')
  async archive(@Param('id') id: string) {
    // Your custom logic
    return this.projectService.archive(id);
  }

  @Get(':id/statistics')
  async getStats(@Param('id') id: string) {
    // Custom aggregation
    return this.projectService.getStatistics(id);
  }
}

Adding Business Logic

typescript

// src/extensions/Project/Project.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class ProjectService {
  async archive(id: string) {
    // Complex business logic
    const project = await this.findOne(id);

    // Archive all tasks
    await this.taskService.archiveByProject(id);

    // Update project status
    return this.update(id, { status: 'archived' });
  }
}

Adding Middleware

typescript

// src/common/interceptors/logging.interceptor.ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    const req = context.switchToHttp().getRequest();
    const { method, url } = req;

    console.log(`${method} ${url}`);

    return next.handle();
  }
}

Environment Configuration

I'll create .env files:

bash

# .env (local development)
NODE_ENV=development
PORT=3001

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_service_db
DB_USER=postgres
DB_PASSWORD=postgres

# Better Auth
AUTH_SECRET=your-secret-key-here
AUTH_URL=http://localhost:3001

# AWS (for production)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Testing

I'll set up testing structure:

typescript

// test/e2e/project.e2e-spec.ts
describe('ProjectController (e2e)', () => {
  let app: INestApplication;

  beforeEach(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/projects (GET)', () => {
    return request(app.getHttpServer())
      .get('/projects')
      .expect(200)
      .expect((res) => {
        expect(res.body.data).toBeInstanceOf(Array);
      });
  });

  it('/projects (POST)', () => {
    return request(app.getHttpServer())
      .post('/projects')
      .send({ name: 'Test Project', organization_id: '...' })
      .expect(201)
      .expect((res) => {
        expect(res.body.name).toBe('Test Project');
      });
  });
});

Verification Checklist

Before marking bootstrap as complete, I verify:

✅ Server starts without errors
✅ Database connection successful
✅ All tables created
✅ OpenAPI docs accessible
✅ CRUD endpoints work for all entities
✅ Multi-tenancy filtering active
✅ Validation works on create/update
✅ Error handling returns proper responses
✅ Environment variables configured
✅ Docker Compose running

Common Issues & Solutions

Issue: "Cannot connect to database" Fix: Ensure npm run compose is running and ports aren't conflicting

Issue: "Module not found" Fix: Run npm install after generating code

Issue: "TypeORM entity not found" Fix: Run npm run provision to sync schema

Issue: "Port 3001 already in use" Fix: Kill existing process: lsof -ti:3001 | xargs kill

What's Next?

After bootstrap, you're ready for:

Frontend Setup - Call frontend-bootstrapper
Authentication - Call auth-implementer
Custom Endpoints - Add business logic to extensions/
Testing - Call test-generator

Ready?

I'll bootstrap a production-ready backend in about 5 minutes. Just provide your schema (or I can call schema-architect first if you don't have one yet).

Do you have a schema ready, or should I design one first?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Backend Bootstrapper

What I Create

1. Apso Service Configuration

2. Generated NestJS Backend

3. Database Setup

4. Development Environment

5. API Documentation

The Bootstrap Process

Step 1: Validate Schema

Step 2: Create Apso Project

Step 3: Configure Schema

Step 4: Generate Code

Step 5: Install Dependencies

Step 6: Start Database

Step 7: Provision Database

Step 8: Start Development Server

Step 9: Verify & Test

Generated API Structure

Standard REST Endpoints

Filtering & Querying

Automatic Features

1. Multi-Tenancy

2. Validation

3. Error Handling

4. Logging

5. OpenAPI Documentation

File Structure

Customization Options

Adding Custom Endpoints

Adding Business Logic

Adding Middleware

Environment Configuration

Testing

Verification Checklist

Common Issues & Solutions

What's Next?

Ready?