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