Event Planning Backend Implementation

Backend implementation for event creation and management API endpoints.

Architecture

Events are managed through a layered architecture:

Client Request → Controller → Service → Repository → Database
                      ↓            ↓
                   Policy      Transaction

Layers

• Controller (apps/server/app/controllers/events_controller.ts) - HTTP request handling, response formatting
• Service (apps/server/app/services/event_service.ts) - Business logic and validation
• Repository (apps/server/app/repositories/event_repository.ts) - Data access with transaction support
• Policy (apps/server/app/policies/event_policy.ts) - Authorization rules
• Transformer (apps/server/app/transformers/event_transformer.ts) - Response serialization
• Event plan controller (apps/server/app/controllers/event_plans_controller.ts) - Event-plan creation under an organization-scoped event
• Event plan service (apps/server/app/services/event_plan_service.ts) - Draft plan creation and duplicate-name validation
• Event plan transformer (apps/server/app/transformers/event_plan_transformer.ts) - Event-plan response serialization

Data Models

The event planning feature uses the following core models:

• Event - Core event entity with organization ownership, status tracking, and flexible metadata for categories, guest counts, and budgets
• Address - Polymorphic location data that can belong to Event, Vendor, or EventPersonnel entities
• EventPlan - Event planning drafts and versions
• EventBlock - Modular event components with polymorphic containers

For complete schema details, field definitions, metadata structure, and relationships, see:

• Event Planning Data Models

Business Logic

Event Ownership & Organization Scope

• Event ownership: Events belong to organizations, not individual users
  • All queries must be scoped to the active organization
  • Cross-organization access is prevented at the application layer
• Collaborator access: Organization members can be added as EventCollaborators (future)
• Personnel management: EventPersonnel are text entries (future)

Address Handling

• Polymorphic relationship: Events can have one associated address
• Transaction-safe: Address creation/updates happen within event transactions
• Optional: Addresses are not required for event creation

For details on event planning entities (EventPlan, EventBlock, Tasks, Vendors, Permissions), see the Event Planning Data Models documentation. Event plan creation is implemented; additional plan operations and most sub-entity APIs are not yet implemented.

API Endpoints

All event endpoints are nested under organization routes and require authentication.

Available Operations

• POST /organizations/:organizationId/events - Create a new event with metadata and optional address
• PATCH /organizations/:organizationId/events/:id - Update existing event (supports partial updates with metadata deep-merging)
• GET /organizations/:organizationId/events/:id - Retrieve event details
• POST /organizations/:organizationId/events/:eventId/plans - Create a new draft event plan

For complete API documentation including request/response formats, metadata schemas, validation rules, deep-merge behavior, and usage examples, see:

• Events API Reference

Authorization

Authorization is handled by the EventPolicy class, which enforces organization-based access control.

Authorization Rules

All event operations check organization membership:

1. Create Event - User must be a member of the target organization
2. View Event - User must be a member of the organization that owns the event
3. Update Event - User must be a member of the organization that owns the event
4. Create Event Plan - User must be able to update the parent event

Organization Access Verification

Organization membership is verified by the OrganizationAuthorizationService:

Response Serialization

Event responses use EventTransformer with two representations:

• toObject(): Used for list views and mutations (id, name, description, organizationId)
• forDetailed(): Extends toObject with timestamps (createdAt, updatedAt)

Implementation: apps/server/app/transformers/event_transformer.ts

Event plan creation responses use EventPlanTransformer.forDetailed() with id, eventId, name, description, state, createdAt, and updatedAt.

Validation

Validation Strategy

• Required fields: Only name is required for event creation
• Optional fields: description, targetDate, status, metadata, address
• Metadata validation: Supports category, guestCount, budgetRange with nested validation
• Address validation: Requires city, optional street address, state, postal code, country
• Custom validators: Currency codes (ISO 4217), country codes (ISO 3166-1 alpha-2), postal codes

Default Values

• status: BACKLOG
• eventType: ONE_OFF
• metadata.budgetRange.currency: CAD (when budgetRange is provided)

For complete validation schemas and field constraints, see:

• apps/server/app/validators/schemas/event.ts
• apps/server/app/validators/schemas/event_plan.ts
• Events API Reference

Error Handling

The implementation uses neverthrow for explicit repository/service flow and self-handling app exceptions for consistent API/log output.

Result Pattern

// Service layer returns Result
const result = await eventService.createEvent(organizationId, data)

// Controller delegates error branches to the shared handler
if (result.isErr()) {
  return handleAppError(result.error, ctx, {
    fallback: {
      message: 'Failed to create event',
      logKey: 'events:create',
    },
  })
}

Error Types

• VineJS validation errors - normalized to 422 with input.{field}.{rule} codes
• RepositoryException - data-access failures with explicit API errors and backend-only log details
• ModelValidationException - domain/model validation failures with exposure-controlled field errors
• EventPlanValidationException - duplicate event-plan name and active-plan invariant failures
• EventPlanServiceException - service-owned event-plan creation failures that are not model validation errors

Future Enhancements

The following features are planned but not yet implemented:

• Role-based permissions (currently organization membership check only)
• Event deletion endpoint
• Event listing with pagination and filtering
• Event plan list/show/update/archive/activate endpoints
• Event search functionality
• Recurring event instance management
• And More..

For the current implementation status, see the actual code in:

• apps/server/app/controllers/events_controller.ts
• apps/server/app/services/event_service.ts
• apps/server/app/repositories/event_repository.ts
• apps/server/app/policies/event_policy.ts