Skip to content

Generate Structure

Method

REST method is adopted.

HTTP Method

POST: Generate Structure

Naming Convention

To unify the naming of query parameters and nodes and improve readability, snake_case is used for URIs and JSON nodes in requests.

Request and Response

Headers

Meta information is set in HTTP headers, not in the response body.

Request Headers

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Generate Structure

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/structure_generation

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID

Request Body

The request body is JSON.

{
  "wireframe_id": "wf-123",
  "detail_design_id": "dd-456",
  "requirement_id": "rq-789"
}

Request Parameters

Name Type Required Description
wireframe_id string Required Associated wireframe ID
detail_design_id string Optional Associated detail design ID
requirement_id string Optional Associated requirement ID

Response

The response is JSON (HTTP status: 201 Created).

{
  "structureId": "st-789",
  "projectId": 2,
  "wireframeId": "wf-123",
  "detailDesignId": "dd-456",
  "requirementId": "rq-789",
  "json": null,
  "status": 0,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

Status Values

Value Description
0 Processing
1 Completed
2 Failed

Response Fields

Name Type Description
structureId string Structure UUID
projectId number Project ID
wireframeId string Wireframe ID
detailDesignId string | null Detail design ID
requirementId string | null Requirement ID
json object | null Generated structure JSON data (set after processing completes)
status number Processing status (0-2)
createdAt number Creation timestamp (epoch milliseconds)
updatedAt number Update timestamp (epoch milliseconds)
deletedAt number | null Deletion timestamp (epoch milliseconds); null if not deleted
createdBy string Creator user ID
updatedBy string Updater user ID
deletedBy string | null Deleter user ID; null if not deleted

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito.

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
Invalid wireframe ID or missing required fields 400 Bad Request
Missing credentials 401 Unauthorized
Insufficient permissions 403 Forbidden
Project, organization, or wireframe not found 404 Not Found
Internal server error 500 Internal Server Error

Processing Flow

  1. Extract organization ID and project ID from path parameters
  2. Extract wireframe ID, detail design ID, and requirement ID from request body
  3. Verify the user has Write permission for the project
  4. Confirm wireframe exists and retrieve its image URL and JSON schema URL
  5. If detail design ID is specified, confirm it exists and retrieve its URL
  6. If requirement ID is specified, confirm it exists and retrieve its URL
  7. Create structure record in the database (json: null, status: 0=processing)
  8. Send structure generation message to SQS queue
  9. Return the created structure information

Detailed Flowchart

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Write permission?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| VerifyWireframe[Verify Wireframe Exists]

    VerifyWireframe --> WFExists{Exists?}
    WFExists -->|No| Err404
    WFExists -->|Yes| VerifyDetail[Verify Detail Design & Requirement<br/>if IDs are specified]

    VerifyDetail --> DetailExists{Exists?}
    DetailExists -->|No| Err404
    DetailExists -->|Yes| CreateDB[Create DB Record<br/>json=null<br/>status=0 processing]

    CreateDB --> SendSQS[Send Message to SQS Queue]

    SendSQS --> SQSResult{Successful?}
    SQSResult -->|No| Err500[500 Internal Server Error]
    SQSResult -->|Yes| Success[201 Created]

Asynchronous Processing

Structures are generated asynchronously by an SQS worker. A background worker updates the status and json field: - 0 (processing) โ†’ 1 (completed) or 2 (failed)

Once completed, the JSON data can be retrieved via the Structure Get API.

SQS Payload

The payload of the message sent to the SQS queue is in the following format.

{
  "project_id": "2",
  "structure_id": "st-789",
  "wireframe_id": "wf-123",
  "wireframe_img_url": "s3://4d-gen-ai-swagger/design.png",
  "wireframe_json_url": "s3://bucket-name/path/to/schema.json",
  "detail_design_id": "dd-456",
  "detail_design_url": "s3://bucket-name/path/to/detail-01.pdf",
  "requirement_id": "rq-789",
  "requirement_url": "s3://bucket-name/path/to/requirements-01.md"
}

SQS Payload Fields

Name Type Required Description
project_id string Required Project ID
structure_id string Required Target structure ID to be generated
wireframe_id string Required Wireframe ID
wireframe_img_url string Required URL of the wireframe image stored in S3
wireframe_json_url string Required URL of the wireframe JSON schema stored in S3
detail_design_id string Optional Detail design ID
detail_design_url string Optional URL of the detail design document stored in S3
requirement_id string Optional Requirement ID
requirement_url string Optional URL of the requirement document stored in S3