project-standalo-note-to-app/.workflow/versions/v001/contracts/api_contract.yml

908 lines
20 KiB
YAML

api_contract:
workflow_version: v001
design_document_revision: 1
generated_at: '2025-12-19T06:08:18.844037'
validated_at: null
status: draft
types:
- id: type_User
name: User
definition:
type: object
properties:
- name: id
type: string
required: true
description: Unique user identifier
- name: email
type: string
required: true
description: User email address for login
- name: name
type: string
required: true
description: User's display name
used_by:
models:
- model_user
responses: []
requests: []
- id: type_Recording
name: Recording
definition:
type: object
properties:
- name: id
type: string
required: true
description: Unique recording identifier
- name: userId
type: string
required: true
description: Owner of this recording
- name: title
type: string
required: true
description: Recording title (auto-generated or user-edited)
- name: audioFilePath
type: string
required: true
description: Path to audio file in MinIO/S3
- name: duration
type: number
required: true
description: Recording duration in seconds
- name: transcript
type: string
required: false
description: Full transcript from Whisper STT
- name: summary
type: string
required: false
description: AI-generated summary from Gemini
- name: isTranscribing
type: boolean
required: true
description: Whether currently transcribing
used_by:
models:
- model_recording
responses: []
requests: []
- id: type_GeneratedApp
name: GeneratedApp
definition:
type: object
properties:
- name: id
type: string
required: true
description: Unique app identifier
- name: userId
type: string
required: true
description: Owner of this app
- name: recordingId
type: string
required: true
description: Source recording that triggered generation
- name: title
type: string
required: true
description: App title from AI analysis
- name: description
type: string
required: false
description: App description
- name: htmlContent
type: string
required: true
description: Complete HTML/CSS/JS for iframe rendering
- name: prdContent
type: string
required: false
description: Product Requirements Document (PRD) generated by AI
- name: uiUxDesign
type: string
required: false
description: UI/UX design notes from AI
- name: appType
type: string
required: false
description: Type of app determined by AI (e.g., todo, calculator, form)
- name: status
type: '''generating'' | ''completed'' | ''failed'''
required: true
description: Generation status
used_by:
models:
- model_generated_app
responses: []
requests: []
- id: type_RegisterUserRequest
name: RegisterUserRequest
definition:
type: object
properties:
- name: email
type: string
required: true
description: User email address
validation: email
- name: name
type: string
required: true
description: User display name
validation: min:1,max:100
- name: password
type: string
required: true
description: Password (min 8 characters)
validation: min:8
used_by:
models: []
responses: []
requests:
- api_register_user
- id: type_LoginUserRequest
name: LoginUserRequest
definition:
type: object
properties:
- name: email
type: string
required: true
description: User email
validation: email
- name: password
type: string
required: true
description: User password
validation: null
used_by:
models: []
responses: []
requests:
- api_login_user
- id: type_LogoutUserRequest
name: LogoutUserRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_logout_user
- id: type_LogoutUserResponse
name: LogoutUserResponse
definition:
type: object
properties:
- name: success
type: boolean
required: true
description: ''
used_by:
models: []
responses:
- api_logout_user
requests: []
- id: type_GetCurrentUserRequest
name: GetCurrentUserRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_get_current_user
- id: type_ListRecordingsRequest
name: ListRecordingsRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_list_recordings
- id: type_CreateRecordingRequest
name: CreateRecordingRequest
definition:
type: object
properties:
- name: audio
type: unknown
required: true
description: Audio file (webm, mp3, wav)
validation: null
- name: title
type: string
required: false
description: Recording title (auto-generated if not provided)
validation: null
- name: duration
type: number
required: true
description: Duration in seconds
validation: null
used_by:
models: []
responses: []
requests:
- api_create_recording
- id: type_GetRecordingRequest
name: GetRecordingRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_get_recording
- id: type_DeleteRecordingRequest
name: DeleteRecordingRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_delete_recording
- id: type_TranscribeRecordingRequest
name: TranscribeRecordingRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_transcribe_recording
- id: type_SummarizeRecordingRequest
name: SummarizeRecordingRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_summarize_recording
- id: type_ListAppsRequest
name: ListAppsRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_list_apps
- id: type_GenerateAppRequest
name: GenerateAppRequest
definition:
type: object
properties:
- name: recordingId
type: string
required: true
description: Source recording ID
validation: null
used_by:
models: []
responses: []
requests:
- api_generate_app
- id: type_GetAppRequest
name: GetAppRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_get_app
- id: type_DeleteAppRequest
name: DeleteAppRequest
definition:
type: object
properties: []
used_by:
models: []
responses: []
requests:
- api_delete_app
endpoints:
- id: api_register_user
method: POST
path: /api/auth/register
path_params: []
query_params: []
request_body:
type_id: type_RegisterUserRequest
content_type: application/json
response:
success:
status: 201
type_id: type_User
is_array: false
errors:
- status: 400
type_id: type_ApiError
description: Validation error
- status: 409
type_id: type_ApiError
description: Email already exists
auth:
required: false
roles: &id001 []
version: 1.0.0
- id: api_login_user
method: POST
path: /api/auth/login
path_params: []
query_params: []
request_body:
type_id: type_LoginUserRequest
content_type: application/json
response:
success:
status: 200
type_id: type_User
is_array: false
errors:
- status: 401
type_id: type_ApiError
description: Invalid credentials
auth:
required: false
roles: &id002 []
version: 1.0.0
- id: api_logout_user
method: POST
path: /api/auth/logout
path_params: []
query_params: []
request_body:
type_id: type_LogoutUserRequest
content_type: application/json
response:
success:
status: 200
type_id: type_LogoutUserResponse
is_array: false
errors: []
auth:
required: true
roles: &id003 []
version: 1.0.0
- id: api_get_current_user
method: GET
path: /api/auth/me
path_params: []
query_params: []
request_body:
type_id: type_GetCurrentUserRequest
content_type: application/json
response:
success:
status: 200
type_id: type_User
is_array: false
errors:
- status: 401
type_id: type_ApiError
description: Not authenticated
auth:
required: true
roles: &id004 []
version: 1.0.0
- id: api_list_recordings
method: GET
path: /api/recordings
path_params: []
query_params:
- name: limit
type: number
required: false
default: 50
description: Maximum number of recordings to return
- name: offset
type: number
required: false
default: 0
description: Number of recordings to skip
request_body:
type_id: type_ListRecordingsRequest
content_type: application/json
response:
success:
status: 200
type_id: type_Recording
is_array: false
errors: []
auth:
required: true
roles: &id005 []
version: 1.0.0
- id: api_create_recording
method: POST
path: /api/recordings
path_params: []
query_params: []
request_body:
type_id: type_CreateRecordingRequest
content_type: application/json
response:
success:
status: 201
type_id: type_Recording
is_array: false
errors:
- status: 400
type_id: type_ApiError
description: Invalid audio file
auth:
required: true
roles: &id006 []
version: 1.0.0
- id: api_get_recording
method: GET
path: /api/recordings/[id]
path_params:
- name: id
type: string
description: Recording ID
query_params: []
request_body:
type_id: type_GetRecordingRequest
content_type: application/json
response:
success:
status: 200
type_id: type_Recording
is_array: false
errors:
- status: 404
type_id: type_ApiError
description: Recording not found
auth:
required: true
roles: &id007 []
version: 1.0.0
- id: api_delete_recording
method: DELETE
path: /api/recordings/[id]
path_params:
- name: id
type: string
description: Recording ID
query_params: []
request_body:
type_id: type_DeleteRecordingRequest
content_type: application/json
response:
success:
status: 200
type_id: type_Recording
is_array: false
errors:
- status: 404
type_id: type_ApiError
description: Recording not found
auth:
required: true
roles: &id008 []
version: 1.0.0
- id: api_transcribe_recording
method: POST
path: /api/recordings/[id]/transcribe
path_params:
- name: id
type: string
description: Recording ID
query_params: []
request_body:
type_id: type_TranscribeRecordingRequest
content_type: application/json
response:
success:
status: 200
type_id: type_Recording
is_array: false
errors:
- status: 404
type_id: type_ApiError
description: Recording not found
auth:
required: true
roles: &id009 []
version: 1.0.0
- id: api_summarize_recording
method: POST
path: /api/recordings/[id]/summarize
path_params:
- name: id
type: string
description: Recording ID
query_params: []
request_body:
type_id: type_SummarizeRecordingRequest
content_type: application/json
response:
success:
status: 200
type_id: type_Recording
is_array: false
errors:
- status: 400
type_id: type_ApiError
description: No transcript available
- status: 404
type_id: type_ApiError
description: Recording not found
auth:
required: true
roles: &id010 []
version: 1.0.0
- id: api_list_apps
method: GET
path: /api/apps
path_params: []
query_params:
- name: limit
type: number
required: false
default: 50
description: Maximum number of apps to return
- name: offset
type: number
required: false
default: 0
description: Number of apps to skip
request_body:
type_id: type_ListAppsRequest
content_type: application/json
response:
success:
status: 200
type_id: type_GeneratedApp
is_array: false
errors: []
auth:
required: true
roles: &id011 []
version: 1.0.0
- id: api_generate_app
method: POST
path: /api/apps/generate
path_params: []
query_params: []
request_body:
type_id: type_GenerateAppRequest
content_type: application/json
response:
success:
status: 201
type_id: type_GeneratedApp
is_array: false
errors:
- status: 400
type_id: type_ApiError
description: Recording has no summary
- status: 404
type_id: type_ApiError
description: Recording not found
auth:
required: true
roles: &id012 []
version: 1.0.0
- id: api_get_app
method: GET
path: /api/apps/[id]
path_params:
- name: id
type: string
description: App ID
query_params: []
request_body:
type_id: type_GetAppRequest
content_type: application/json
response:
success:
status: 200
type_id: type_GeneratedApp
is_array: false
errors:
- status: 404
type_id: type_ApiError
description: App not found
auth:
required: true
roles: &id013 []
version: 1.0.0
- id: api_delete_app
method: DELETE
path: /api/apps/[id]
path_params:
- name: id
type: string
description: App ID
query_params: []
request_body:
type_id: type_DeleteAppRequest
content_type: application/json
response:
success:
status: 200
type_id: type_GeneratedApp
is_array: false
errors:
- status: 404
type_id: type_ApiError
description: App not found
auth:
required: true
roles: &id014 []
version: 1.0.0
frontend_calls:
- id: call_page_dashboard_api_get_current_user
source:
entity_id: page_dashboard
file_path: app/dashboard/page.tsx
endpoint_id: api_get_current_user
purpose: Display user info
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_page_dashboard_api_list_recordings
source:
entity_id: page_dashboard
file_path: app/dashboard/page.tsx
endpoint_id: api_list_recordings
purpose: Show recent recordings
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_page_recordings_api_list_recordings
source:
entity_id: page_recordings
file_path: app/recordings/page.tsx
endpoint_id: api_list_recordings
purpose: Display all recordings
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_page_recording_detail_api_get_recording
source:
entity_id: page_recording_detail
file_path: app/recordings/[id]/page.tsx
endpoint_id: api_get_recording
purpose: Display recording details
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_page_apps_api_list_apps
source:
entity_id: page_apps
file_path: app/apps/page.tsx
endpoint_id: api_list_apps
purpose: Display generated apps gallery
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_page_app_detail_api_get_app
source:
entity_id: page_app_detail
file_path: app/apps/[id]/page.tsx
endpoint_id: api_get_app
purpose: Display app in iframe
trigger: onLoad
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Update state
error_action: Show error
- id: call_component_login_form_api_login_user
source:
entity_id: component_login_form
file_path: app/components/LoginForm.tsx
endpoint_id: api_login_user
purpose: Call api_login_user
trigger: onSubmit
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Handle response
error_action: Show error
- id: call_component_register_form_api_register_user
source:
entity_id: component_register_form
file_path: app/components/RegisterForm.tsx
endpoint_id: api_register_user
purpose: Call api_register_user
trigger: onSubmit
request_mapping:
from_props: []
from_state: []
from_form: []
response_handling:
success_action: Handle response
error_action: Show error
backend_routes:
- id: route_post_auth_register
endpoint_id: api_register_user
file_path: app/api/auth/register/route.ts
export_name: POST
uses_models:
- model_user
uses_services: []
must_validate: []
must_authenticate: false
must_authorize: *id001
- id: route_post_auth_login
endpoint_id: api_login_user
file_path: app/api/auth/login/route.ts
export_name: POST
uses_models:
- model_user
uses_services: []
must_validate: []
must_authenticate: false
must_authorize: *id002
- id: route_post_auth_logout
endpoint_id: api_logout_user
file_path: app/api/auth/logout/route.ts
export_name: POST
uses_models: []
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id003
- id: route_get_auth_me
endpoint_id: api_get_current_user
file_path: app/api/auth/me/route.ts
export_name: GET
uses_models:
- model_user
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id004
- id: route_get_recordings
endpoint_id: api_list_recordings
file_path: app/api/recordings/route.ts
export_name: GET
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id005
- id: route_post_recordings
endpoint_id: api_create_recording
file_path: app/api/recordings/route.ts
export_name: POST
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id006
- id: route_get_recordings_[id]
endpoint_id: api_get_recording
file_path: app/api/recordings/[id]/route.ts
export_name: GET
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id007
- id: route_delete_recordings_[id]
endpoint_id: api_delete_recording
file_path: app/api/recordings/[id]/route.ts
export_name: DELETE
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id008
- id: route_post_recordings_[id]_transcribe
endpoint_id: api_transcribe_recording
file_path: app/api/recordings/[id]/transcribe/route.ts
export_name: POST
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id009
- id: route_post_recordings_[id]_summarize
endpoint_id: api_summarize_recording
file_path: app/api/recordings/[id]/summarize/route.ts
export_name: POST
uses_models:
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id010
- id: route_get_apps
endpoint_id: api_list_apps
file_path: app/api/apps/route.ts
export_name: GET
uses_models:
- model_generated_app
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id011
- id: route_post_apps_generate
endpoint_id: api_generate_app
file_path: app/api/apps/generate/route.ts
export_name: POST
uses_models:
- model_generated_app
- model_recording
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id012
- id: route_get_apps_[id]
endpoint_id: api_get_app
file_path: app/api/apps/[id]/route.ts
export_name: GET
uses_models:
- model_generated_app
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id013
- id: route_delete_apps_[id]
endpoint_id: api_delete_app
file_path: app/api/apps/[id]/route.ts
export_name: DELETE
uses_models:
- model_generated_app
uses_services: []
must_validate: []
must_authenticate: true
must_authorize: *id014