api-user Overview

apps/app is the REST API for end users. It is implemented with Hono + Bun and uses PostgreSQL as its data store. Heavy processing such as code generation is delegated asynchronously to AI workers via SQS.

Architecture

A 4-layer structure: Routes → Services → Repositories → Database.

Client Request
    ↓
Middlewares (auth, logging, error handling)
    ↓
Routes (request validation, response formatting)
    ↓
Services (business logic)
    ↓
Repositories (data access)
    ↓
Database / External Services (AWS Cognito, S3, SQS)

Endpoint List

All endpoints are versioned under the /v1 prefix.

Path	File	Description
`/v1/auth/*`	`routes/v1/auth.ts`	Authentication and session management
`/v1/users/*`	`routes/v1/user.ts`	User management
`/v1/organizations/*`	`routes/v1/organization.ts`	Organization CRUD
`/v1/projects/*`	`routes/v1/project.ts`	Project management
`/v1/designs/*`	`routes/v1/design.ts`	Design file management
`/v1/code/*`	`routes/v1/code.ts`	Code operations
`/v1/des2code/*`	`routes/v1/des2code.ts`	Des2Code operations
`/v1/organizations/:organizationId/projects/:projectId/page-imports/*`	`routes/v1/page-import.ts`	Public URL capture creation, lifecycle polling, and completed-import discovery
`/v1/organizations/:organizationId/projects/:projectId/code2des/*`	`routes/v1/code2des.ts`	Conversion of a selected completed Page Import and Figma placement tracking
`/v1/organizations/:organizationId/projects/:projectId/code2wf/` (planned)*	`routes/v1/code2wf.ts`	Code2WF generation, result discovery, and Figma placement
`/v1/generated-code/*`	`routes/v1/generated-code.ts`	Code generation
`/v1/figma/*`	`routes/v1/figma.ts`	Figma API integration
`/v1/webhooks/*`	`routes/v1/webhook.ts`	Webhook receiver for AI workers
`/v1/ping`	`routes/v1/ping.ts`	Health check

Middleware Pipeline

Middleware	File	Role
`requestId()`	`hono/request-id`	Attaches a unique request ID for tracing
`winstonLogger()`	`middlewares/winston-logger.ts`	Structured request / response logging (including duration)
`cors()`	`hono/cors`	Cross-origin resource sharing
`compress()`	`hono/compress`	Gzip response compression
`rateLimit()`	`middlewares/rate-limit.ts`	Request rate limiting
`protectedRoute`	`middlewares/protected-route.ts`	JWT verification and Cognito sub extraction
`errorHandler`	`middlewares/error-handler.ts`	Centralized error handling with unified response format

Authentication Flow

sequenceDiagram
    participant User as User
    participant API as API Gateway
    participant Lambda as Lambda (api-user)
    participant Cognito as AWS Cognito

    User->>API: POST /v1/auth/login
    API->>Lambda: Forward request
    Lambda->>Cognito: initiateAuth()
    Cognito-->>Lambda: JWT access token
    Lambda-->>User: 200 { token, user }

    User->>API: Call protected endpoint
    API->>Lambda: Authorization: Bearer <token>
    Lambda->>Lambda: JWT verification in protectedRoute middleware
    Lambda-->>User: Response

Authorization (organization membership validation, resource ownership checks) is implemented in the service layer.

Error Handling

All errors are returned in the following JSON format.

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": {}
  }
}

Status	Usage
`400 Bad Request`	Invalid input data
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`409 Conflict`	Resource conflict (e.g. duplicate)
`500 Internal Server Error`	Unexpected server error

Validation

Zod schemas validate all input points of the request.

Input type	Access method
Request body	`c.req.valid('json')`
Path parameters	`c.req.valid('param')`
Query parameters	`c.req.valid('query')`

Responses are also covered by OpenAPI schemas (@hono/zod-openapi) to ensure type safety and contract compliance.

Logging

All operations are emitted as structured logs.

logger.info('Operation completed', {
  operation: 'domain.action',
  duration: 123,
  requestId: 'uuid',
  userId: 'user-id',
});

Level	Usage
`info`	Successful operations
`warn`	Recoverable issues
`error`	Failures and exceptions
`debug`	Detailed debug information (development only)

Testing

Type	Directory	Contents
Unit tests	`__tests__/unit/`	Service logic, repository operations, utilities
Integration tests	`__tests__/integration/`	Full request-response cycle, database interaction

bun test