interaqt 0.7.4 → 0.8.1

package/agent/.claude/agents/requirements-analysis-handler.md

@@ -45,16 +45,61 @@ Concepts extracted from goals and requirements. Supported data types:
 - View: Entity sorting, grouping, pagination results
 - Aggregated Value: Results of aggregate calculations
 
+**Entity-Relation Design Principles:**
+- **Entities MUST NOT contain foreign key properties** (e.g., no `userId`, `bookId`, `dormitoryId`)
+- **Relations are the ONLY way to connect entities** - they replace traditional foreign key patterns
+- Entity properties should only contain intrinsic attributes of that entity
+- Example: Use `BookAuthorRelation` connecting Book and Author, NOT `authorId` property on Book
+
 ## Rules/Constraints
 Constraints expressed on roles, interactions, and data in requirements.
 
+## External System Boundary
+
+**⚠️ CRITICAL: Distinguish between user requirements and external system events.**
+
+**User Requirements (analyze as requirements):**
+- Operations initiated by human users within current system
+- Data that users need to read/create/update/delete
+- Role should be user roles (e.g., "User", "Administrator")
+
+**External System Events (NOT requirements):**
+- Webhook callbacks from external services
+- External system state changes that need to be synced
+- System-to-system data synchronization
+- Handle via external event entities in Task 1.4, document in Task 1.3
+
+**Interactions vs Integrations:**
+- **Interactions**: User actions within current system (role = user roles like "Reader", "Administrator")
+- **Integrations**: External system communications (documented in Task 1.3 integration.json)
+- ❌ NEVER use "System" as role in interactions
+- ❌ NEVER create interactions for external API calls or webhooks
+
+**Examples:**
+- ✅ User reads data → Create read requirement & interaction
+- ✅ User initiates payment → Create write requirement & interaction  
+- ❌ Update data from webhook → External event entity (Task 1.4), NOT requirement
+- ❌ Call external API → Integration (Task 1.3), NOT interaction
+
 # Task 1: Requirements Analysis
 
-**📖 START: Read `docs/STATUS.json` to check current progress before proceeding.**
+**📖 START: Determine current module and check progress before proceeding.**
+
+**🔴 STEP 0: Determine Current Module**
+1. Read module name from `.currentmodule` file in project root
+2. If file doesn't exist, STOP and ask user which module to work on
+3. Use this module name for all subsequent file operations
+
+**🔴 CRITICAL: Module-Based File Naming**
+- All output files MUST be prefixed with current module name from `.currentmodule`
+- Format: `{module}.{filename}` (e.g., if module is "user", output `requirements/user.goals-analysis.json`)
+- All input file references MUST also use module prefix when reading previous outputs
+- Module status file location: `docs/{module}.status.json`
 
-**🔄 Update `docs/STATUS.json`:**
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1",
   "completed": false
 }
@@ -62,9 +107,10 @@ Constraints expressed on roles, interactions, and data in requirements.
 
 ## Task 1.1: Goal Analysis and Refinement
 
-**🔄 Update `docs/STATUS.json`:**
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1.1",
   "completed": false
 }
@@ -101,9 +147,9 @@ User input may contain:
 
 3. **Assign Goal IDs**: Each goal must have a unique identifier (G001, G002, etc.)
 
-### Output: goals-analysis.json
+### Output: {module}.goals-analysis.json
 
-Create `requirements/goals-analysis.json`:
+Create `requirements/{module}.goals-analysis.json` (replace `{module}` with actual module name from `.currentmodule`):
 
 ```json
 {
@@ -146,9 +192,10 @@ Create `requirements/goals-analysis.json`:
 }
 ```
 
-**✅ END Task 1.1: Update `docs/STATUS.json`:**
+**✅ END Task 1.1: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1.1",
   "completed": true
 }
@@ -162,9 +209,10 @@ git commit -m "feat: Task 1.1 - Complete goal analysis and refinement"
 
 ## Task 1.2: Functional Requirements Analysis
 
-**🔄 Update `docs/STATUS.json`:**
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1.2",
   "completed": false
 }
@@ -174,6 +222,8 @@ git commit -m "feat: Task 1.1 - Complete goal analysis and refinement"
 
 We focus on data-centric requirements. Human software usage delegates unsuitable tasks (storage, computation) to support better decision-making. Since decisions require information, we start with **READ requirements** as the root.
 
+**Note:** See "External System Boundary" in Core Concepts for distinguishing user requirements from external system events.
+
 ### ⚠️ CRITICAL: Reactive Framework Principles
 
 **DO NOT create "automatic system" requirements.** Our framework is reactive - avoid designing autonomous system behaviors.
@@ -196,10 +246,6 @@ We focus on data-centric requirements. Human software usage delegates unsuitable
    - ❌ WRONG: "Replace old data with new data"
    - ✅ CORRECT: "Create new data + Delete old data" (as two separate operations)
 
-**For unavoidable side-effect requirements** (e.g., "automatically send notification"):
-- Design the requirement but explicitly mark as **"Currently Not Supported"**
-- Document: "This requirement involves automatic side-effects which are not supported by the current reactive framework"
-
 **Examples of Proper Transformation:**
 - "Auto-calculate late fees" → "Late fee amount is computed based on overdue days and daily rate"
 - "Auto-send reminders" → "Reminder needed status is computed based on due date" + "Send reminder interaction"
@@ -207,6 +253,28 @@ We focus on data-centric requirements. Human software usage delegates unsuitable
 - "Auto-update inventory" → "Available count is computed based on total copies minus borrowed copies"
 - "Replace employee profile" → "Create new employee profile" + "Delete old employee profile" (two interactions)
 
+**For unavoidable side-effect requirements** (e.g., "automatically send notification"):
+- Design the requirement but explicitly mark as **"Requires External Integration Support"**
+- Document: "This requirement involves automatic side-effects which require external integration support"
+
+### External Integration Requirements
+
+**Framework Limitations:**
+- Current framework only expresses business logic representable in relational databases
+- External side-effects requiring third-party APIs must be identified separately
+
+**External integrations include:**
+- Payment processing (e.g., connecting to payment gateways)
+- AI/ML services (e.g., image generation, text analysis)
+- File storage services (e.g., cloud storage uploads)
+- Email/SMS notifications via external providers
+- Third-party API integrations
+
+**Documentation Process:**
+- Identify these requirements during analysis
+- Document in `requirements/{module}.integration.json`
+- Will be implemented by other agents or engineers
+
 ### Step 1: Create Read Requirements from Goals
 
 Read requirements express:
@@ -216,6 +284,24 @@ Read requirements express:
 - **Goal**: Direct service goal (derived requirements may not have goals)
 - **Parent Requirement**: Which requirement this derives from (root read requirements don't have parents)
 
+**⚠️ IMPORTANT: AI Generation Requirements as Read Operations**
+
+When users need AI-generated content (TTS, image generation, video generation, text generation, etc.), treat these as **READ requirements first**.
+
+**Conceptual Model:**
+- AI generation is "reading" content produced by an AI model based on input parameters
+- The generation process itself is an external integration (documented in Task 1.3)
+- The requirement expresses what data the user wants to "read/retrieve"
+
+**Examples:**
+- "Read AI-generated image based on text description"
+- "Read TTS audio based on text content"
+
+**Pattern:**
+```
+Read [AI-generated content type] based on [input parameters]
+```
+
 ### Step 2: Derive Create/Update/Delete Requirements
 
 From read requirements, derive:
@@ -223,6 +309,108 @@ From read requirements, derive:
 - **Update**: Based on business scenario (some data may be immutable)
 - **Delete**: Based on business scenario (some systems forbid deletion)
 
+**⚠️ IMPORTANT: AI-Generated Content as Computed Data**
+
+Data generated by external AI services should be treated as **computed results**, similar to aggregated values or derived properties.
+
+**Key Principles:**
+- AI-generated content is typically **immutable** - cannot be directly modified
+- Do NOT derive standalone update requirements for AI-generated content
+- Do NOT derive standalone delete requirements for AI-generated content
+- Any updates/deletes should be **cascading operations** tied to source data changes
+
+**Examples:**
+
+✅ **CORRECT - No standalone update/delete:**
+```
+R001 (read): "Read TTS audio based on article content"
+R101 (create): "Create article with text content"
+// AI-generated audio is computed from article.content
+// ❌ Do NOT create: "Update TTS audio" 
+// ✅ If article.content updates → audio regenerates automatically (computed)
+// ✅ If article deletes → audio deletes cascadingly (not standalone operation)
+```
+
+✅ **CORRECT - Cascading delete only:**
+```
+R001 (read): "Read AI-generated image based on prompt"
+R101 (create): "Create image generation request with prompt"
+R103 (delete): "Delete image generation request" 
+// Deleting the request cascades to delete the generated image
+// NOT a separate "Delete AI-generated image" requirement
+```
+
+❌ **WRONG - Standalone operations:**
+```
+R001 (read): "Read AI-generated video"
+R102 (update): "Update AI-generated video" // ❌ Cannot edit AI output directly
+R103 (delete): "Delete AI-generated video" // ❌ Should be cascading, not standalone
+```
+
+**🔴 CRITICAL: Minimal Derivation Principle**
+
+**Only derive operations explicitly needed by user's business requirements:**
+- ❌ NEVER derive operations "for completeness" or "just in case"
+- ❌ NEVER automatically add Administrator role for operations
+- ✅ Only derive what user explicitly mentioned or clearly implied
+
+**When deriving UPDATE requirements:**
+- ✅ Derive if user explicitly mentioned modification
+- ❌ DO NOT derive if property changes indirectly (e.g., balance = sum of transactions)
+- ❌ DO NOT derive "admin adjustment" unless user mentioned it
+
+**When introducing new ROLES:**
+- ✅ Only use roles user explicitly mentioned
+- ❌ NEVER assume operations "should be admin-only"
+- ❌ NEVER add Administrator role without user request
+
+**Examples:**
+
+❌ **WRONG - Over-derivation:**
+```json
+{
+  "id": "R001",
+  "type": "read",
+  "title": "View gift balance"
+}
+// Deriving:
+{
+  "id": "R102",
+  "type": "update", 
+  "title": "Adjust balance (Administrator)",  // ❌ User never mentioned!
+  "role": "Administrator"  // ❌ Role introduced without user input!
+}
+```
+
+✅ **CORRECT - User-driven derivation:**
+```json
+{
+  "id": "R001",
+  "type": "read",
+  "title": "View gift balance"
+}
+// Deriving:
+{
+  "id": "R101",
+  "type": "create",
+  "title": "Recharge balance",  // ✅ User mentioned "recharge"
+  "role": "User"  // ✅ User role from context
+}
+// Balance changes through recharge/donation creates, no direct update needed
+```
+
+**Computed/Derived Properties:**
+
+Some properties change indirectly through other operations:
+- Balance properties (sum of transactions)
+- Count properties (count of related entities)
+- Status properties (derived from state)
+
+For these:
+- ❌ DO NOT create direct update requirements
+- ✅ They change through create/delete of related entities
+- Document as computed in Task 1.4
+
 Expression format:
 - **Parent Requirement**: Derivation source
 - **Role**: Actor performing the action
@@ -237,13 +425,9 @@ Continue deriving read requirements from write requirements:
 - Example: Before modifying book inventory, need to read current inventory for verification
 - This creates "Get book inventory count" read requirement
 
-### Integration of User-Provided Requirements
-
-Integrate requirements extracted in Task 1.1 into this analysis.
+### Output: {module}.requirements-analysis.json
 
-### Output: requirements-analysis.json
-
-Create `requirements/requirements-analysis.json`:
+Create `requirements/{module}.requirements-analysis.json` (replace `{module}` with actual module name from `.currentmodule`):
 
 ```json
 {
@@ -334,9 +518,10 @@ Create `requirements/requirements-analysis.json`:
 }
 ```
 
-**✅ END Task 1.2: Update `docs/STATUS.json`:**
+**✅ END Task 1.2: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1.2",
   "completed": true
 }
@@ -348,35 +533,324 @@ git add .
 git commit -m "feat: Task 1.2 - Complete functional requirements analysis"
 ```
 
-## Task 1.3: Data Concept Extraction
+## Task 1.3: External Integration Analysis
 
-**🔄 Update `docs/STATUS.json`:**
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1.3",
   "completed": false
 }
 ```
 
+### Framework Limitations
+
+**Current framework capabilities:**
+- Expresses business logic representable in relational databases
+- Supports reactive data computations and constraints
+- Handles CRUD operations with complex business rules
+
+**External side-effects requiring third-party APIs must be identified separately.**
+
+### What is NOT an Integration
+
+**⚠️ CRITICAL: Intra-Project Module Access**
+
+**DO NOT treat inter-module data access within the same project as integration:**
+- Data access between modules in the same project is handled through the framework's entity and relation system
+- Modules can directly reference and use entities/relations defined in other modules
+- Example: If the "payment" module needs to access "User" entity defined in the "basic" module, this is NOT an integration - it's normal module dependency
+- Cross-module data access should be documented in the data concepts (Task 1.4) and interaction design (Task 1.5), NOT in integration analysis
+
+**ONLY treat as integration when:**
+- The external system is completely independent (different codebase, different deployment)
+- Communication requires network calls (HTTP/HTTPS, WebSocket, gRPC, etc.)
+- The external system has its own API/interface that we must call
+- The external system is managed by third parties or different teams
+
+**Examples:**
+- ✅ INTEGRATION: Calling Stripe API for payment processing
+- ✅ INTEGRATION: Using AWS S3 for file storage
+- ✅ INTEGRATION: Connecting to external AI service for content generation
+- ❌ NOT INTEGRATION: "payment" module reading "User" entity from "basic" module
+- ❌ NOT INTEGRATION: "content" module using "UserProfile" relation from "user" module
+- ❌ NOT INTEGRATION: "order" module computing values based on "Product" entity from "catalog" module
+
+### Types of External Integrations
+
+**⚠️ CRITICAL: Integration Type Classification**
+
+Every integration must be classified into one of three types:
+
+1. **Type 1: API Call for Return Value** (`api-call-with-return`)
+   - Purpose: Call external API to get a specific result that will be used by business logic
+   - Examples: TTS (text-to-speech), AI image generation, AI video generation
+   - Characteristics:
+     - System needs the return value for business data
+     - Business entities depend on the API result
+     - Return value must be stored and referenced
+
+2. **Type 2: Side Effect Execution** (`side-effect`)
+   - Purpose: Execute an external action without needing a return value
+   - Examples: Send email, send IM message, send push notification
+   - Characteristics:
+     - System doesn't need the return value
+     - Action completion is sufficient
+     - May track status but not content
+
+3. **Type 3: Stateful System Integration** (`stateful-system`)
+   - Purpose: Integrate with external systems that maintain their own state
+   - Examples: Payment systems (Stripe, Alipay, PayPal), third-party order systems
+   - Characteristics:
+     - External system has its own state machine
+     - Need to sync state bidirectionally
+     - May involve multiple state transitions
+     - Often involves webhooks for state updates
+
+**Additional integration examples:**
+- **AI/ML services**: Image generation, text analysis, recommendation engines (Type 1)
+- **File storage services**: Cloud storage uploads (S3, OSS, etc.) (Type 1)
+- **Communication services**: Email/SMS notifications via external providers (Type 2)
+- **Third-party APIs**: Classify based on purpose (Type 1, 2, or 3)
+
+### Analysis Process
+
+1. **Review requirements** from Task 1.2 to identify external integration needs
+2. **For each external integration**:
+   - Describe the interaction flow between current system and external system
+   - Clearly mark system boundaries (what happens where)
+   - Document data flow and transformations
+   - Specify error handling strategies
+
+### Content Requirements
+
+1. **Interaction Flow**: Describe simple, clear interaction flows with external systems
+2. **System Boundaries**: Clearly mark:
+   - Which data resides in the current system
+   - Which user interactions occur in the current system
+   - Which actions/data belong to external systems
+3. **Structured Format**: Use the JSON template below
+
+**🔴 CRITICAL: Integration Type Classification**
+
+For EVERY integration, you MUST:
+1. **Determine the type** using the classification from the "Types of External Integrations" section above
+2. **Fill the `type` field** with one of: `api-call-with-return`, `side-effect`, or `stateful-system`
+3. **Explain your choice** in the `type_explanation` field
+4. This type field is CRITICAL for the next phase (data design) to create proper API Call entities
+
+### Output: {module}.integration.json
+
+Create `requirements/{module}.integration.json` (replace `{module}` with actual module name from `.currentmodule`):
+
+```json
+{
+  "integration_metadata": {
+    "timestamp": "YYYY-MM-DD HH:mm:ss",
+    "module": "{module}",
+    "version": "1.0.0"
+  },
+  "integrations": [
+    {
+      "id": "INT001",
+      "name": "[Integration name, e.g., PaymentProcessing]",
+      "type": "api-call-with-return|side-effect|stateful-system",
+      "type_explanation": "[REQUIRED: Explain why this specific type was chosen. Type 1 (api-call-with-return): System needs the return value for business data. Type 2 (side-effect): Execute action without needing return value. Type 3 (stateful-system): External system maintains state that needs bidirectional sync.]",
+      "external_system": "[External system name, e.g., Stripe, Alipay]",
+      "purpose": "[Brief description of why this integration is needed]",
+      "related_requirements": ["R101", "R102"],
+      "flow_description": "[Natural language description of the complete interaction flow between current system and external system. Describe what happens step by step, clearly marking which actions occur in current system vs external system.]",
+      "user_interactions": {
+        "in_current_system": [
+          "[User action that happens in current system, e.g., 'User clicks purchase button', 'User fills out payment form']"
+        ],
+        "in_external_system": [
+          "[User action that happens in external system, e.g., 'User authenticates in payment gateway', 'User confirms payment in third-party app']"
+        ]
+      },
+      "current_system_data": [
+        {
+          "entity": "EntityName",
+          "properties": ["property1", "property2"],
+          "usage": "[How this data is used: e.g., 'Read before sending to external system', 'Updated after receiving response']"
+        }
+      ],
+      "notes": "[Additional notes about this integration]"
+    }
+  ]
+}
+```
+
+### Example: Payment Processing Integration
+
+```json
+{
+  "integration_metadata": {
+    "timestamp": "2024-01-15 10:30:00",
+    "module": "payment",
+    "version": "1.0.0"
+  },
+  "integrations": [
+    {
+      "id": "INT001",
+      "name": "PaymentProcessing",
+      "type": "stateful-system",
+      "external_system": "Stripe",
+      "purpose": "Process user payments for premium features",
+      "related_requirements": ["R105"],
+      "flow_description": "User clicks 'Purchase Premium' button in current system. System reads User.id and Product.price, creates PaymentIntent with status='pending', then sends payment request (amount, currency, payment_method) to Stripe. Stripe processes the payment externally (validates payment method, checks for fraud, processes transaction). After processing, Stripe returns payment result (payment_status, transaction_id) to current system. Current system receives the response and updates PaymentIntent.status, Order.paymentStatus, and User.premiumUntil accordingly. If payment fails, system sets PaymentIntent.status to 'failed' and notifies user to retry.",
+      "user_interactions": {
+        "in_current_system": [
+          "User clicks 'Purchase Premium' button to initiate payment",
+          "User selects product and views pricing information",
+          "User receives payment result notification (success or failure)"
+        ],
+        "in_external_system": [
+          "User enters payment card details in Stripe hosted page",
+          "User completes two-factor authentication in their bank app",
+          "User confirms the payment in Stripe interface"
+        ]
+      },
+      "current_system_data": [
+        {
+          "entity": "PaymentIntent",
+          "properties": ["status", "amount", "transactionId"],
+          "usage": "Created with status='pending' before sending request to Stripe. Updated with final status and transactionId after receiving Stripe response."
+        },
+        {
+          "entity": "Order",
+          "properties": ["paymentStatus", "totalAmount"],
+          "usage": "Updated with payment status after receiving confirmation from Stripe."
+        },
+        {
+          "entity": "User",
+          "properties": ["id", "premiumUntil"],
+          "usage": "User.id read to identify the purchaser. User.premiumUntil updated after successful payment."
+        },
+        {
+          "entity": "Product",
+          "properties": ["price"],
+          "usage": "Read to determine payment amount before sending to Stripe."
+        }
+      ],
+      "notes": "Stripe webhook integration needed for handling delayed status updates and payment confirmations."
+    }
+  ]
+}
+```
+
+**✅ END Task 1.3: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
+```json
+{
+  "module": "<keep existing value>",
+  "currentTask": "Task 1.3",
+  "completed": true
+}
+```
+
+**📝 Commit changes:**
+```bash
+git add .
+git commit -m "feat: Task 1.3 - Complete external integration analysis"
+```
+
+## Task 1.4: Data Concept Extraction
+
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
+```json
+{
+  "module": "<keep existing value>",
+  "currentTask": "Task 1.4",
+  "completed": false
+}
+```
+
 ### Extraction Process
 
 Extract all necessary data concepts from requirements using supported data types.
 
-**⚠️ CRITICAL DESIGN PRINCIPLE: Entity Property Design**
-- **Entities MUST NOT contain foreign key properties** (e.g., no `userId`, `bookId`, `dormitoryId` properties)
-- **All relationships between entities MUST be defined through explicit Relations**
-- **Entity properties should only contain intrinsic attributes** of that entity
-- **Example:**
-  - ❌ WRONG: Book entity with `authorId` property
-  - ✅ CORRECT: Book entity with `title` property + BookAuthorRelation connecting Book and Author
-
-### Step 1: Entity Identification and Analysis
+**Note:** See "Entity-Relation Design Principles" in Core Concepts for entity design rules.
+
+**🔴 CRITICAL: Module Boundary - User Entity Rule**
+
+User entity can ONLY be defined in the "basic" module. All other modules MUST NOT define or extend User entity.
+
+**If current module is NOT "basic" and needs user-related data:**
+1. ❌ NEVER define User entity in your `entities` array
+2. ❌ NEVER add properties to User entity  
+3. ✅ CREATE a separate 1:1 entity linked to User via relation
+
+**Example:** If "donate" module needs `giftBalance`:
+- ❌ WRONG: Add `giftBalance` property to User entity
+- ✅ CORRECT: Create `UserGiftProfile` entity with `giftBalance`, link via `UserGiftProfileRelation` (1:1)
+
+### Step 0: External Integration Entities (if applicable)
+
+**⚠️ CRITICAL: Always process integration entities FIRST before business entities**
+
+If `requirements/{module}.integration.json` exists and contains integrations:
+
+**Why this matters:**
+- External API calls are time-consuming and error-prone
+- Explicit modeling enables retry and error handling interactions
+- Users need visibility into integration status and failures
+
+**For EACH integration, create these entities:**
+
+1. **API Call Entity** - `{integration}{APIname}Call`
+   - Purpose: Track each API call execution (parameters, status, result, timing)
+   - Required properties:
+     - `status`: string ('pending' | 'processing'|'completed' | 'failed') - Computed from integration events
+     - `externalId`: string - External task/job ID returned by the external API - Computed from the 'initialized' event
+     - `requestParams`: object (sent to external API)
+     - `responseData`: object (returned from external API) - Computed from integration events
+     - `createdAt`: timestamp
+     - `completedAt`: timestamp (nullable) - Computed from integration events
+     - `error`: object (nullable) - Computed from integration events
+   - **Statemachine Computation**: The properties `status`, `externalId`, `responseData`, `error`, and `completedAt` are computed based on related integration events using statemachine transitions
+   - **🔴 CRITICAL: externalId Computation**:
+     - The `externalId` property is computed from the integration event with `eventType: 'initialized'`
+     - The framework guarantees that the 'initialized' event contains both `entityId` (matching this API Call's id) and `externalId` (from external system)
+     - This establishes the link between the API Call entity and the external system's task/job ID
+     - Subsequent events use `externalId` to locate and update the correct API Call record
+   - Examples: `VolcTTSCall`, `StripePaymentCall`, `VolcImageGenerationCall`
+
+2. **Integration Event Entity** - `{integration}{APIname}Event` (for webhook/callback/initialize)
+   - Purpose: Record external system state changes or api call process changes
+   - Required properties:
+     - `eventType`: string ('initialized' | 'processing' | 'completed' | 'failed')
+     - `entityId`: string(nullable) - API Call entity id
+     - `externalId`: string - External task/job ID to track which API call this event relates to
+     - `status`: string
+     - `createdAt`: timestamp
+     - `data`: object (event payload)
+   - Mark as: `entityType: "api-event"`
+   - Examples: `VolcTTSEvent`, `StripePaymentEvent`
+   - **🔴 CRITICAL: The 'initialized' Event Type**:
+     - The `initialized` event is special: it ALWAYS contains both `entityId` and `externalId`
+     - This event associates the API Call entity's `id` with the external system's `externalId`
+     - This association enables subsequent events to find the correct API Call record using `externalId`
+
+3. **API Call Relation**
+   - Connect `{integration}{APIname}Call` to business entity needing the result
+   - Examples: `GreetingVolcTTSCallRelation`, `OrderStripePaymentCallRelation`
+   - **⚠️ CRITICAL: MUST be 1:n relation** (one business entity to many API calls)
+     - Reason: API calls are fragile and may fail, requiring retries
+     - Reason: Users may be unsatisfied with results and request regeneration
+     - Example: `GreetingVolcTTSCallRelation` should be 1:n (one Greeting has many VolcTTSCall attempts)
+     - The business entity uses the LATEST successful API call result
+
+**Document in output:** Add these to `entities` and `relations` arrays with clear notes about integration purpose.
+
+### Step 1: Business Entity Identification and Analysis
 
 Extract nouns as potential entities:
 - Identify main business objects
 - Determine data needing persistence and tracking
 - Identify objects with unique identity and lifecycle
-- **Ensure NO foreign key properties** - move these to Relations
+- CHECK: If you identified "User" with new properties, STOP - create separate 1:1 entity instead
+
 
 ### Step 2: Property Analysis
 
@@ -386,6 +860,14 @@ For each entity property:
 - **Computation Method**: For aggregated or computed values
 - **Data Dependencies**: For computed values, list dependencies
 
+**Computation Methods**:
+- **aggregation**: Property computed from aggregate calculations (sum, count, etc.)
+- **statemachine**: Property computed from state transitions based on integration events (for API Call entities)
+
+**API Call Entity Properties**:
+- For API Call entities, the properties `status`, `externalId`, `responseData`, `error`, and `completedAt` are computed using `statemachine` method
+- These properties transition based on related integration events
+
 **Hard Deletion Property**:
 - If delete requirements in Task 1.2 specify `"deletion_type": "hard"`
 - Add **HardDeletionProperty** to the entity/relation
@@ -393,30 +875,12 @@ For each entity property:
 
 ### Step 3: Relation Identification and Analysis
 
-**Relations are the ONLY way to connect entities** - they replace traditional foreign key patterns.
-
 From verb phrases in requirements, identify relations with these key attributes:
 - **type**: Cardinality (1:1, 1:n, n:1, n:n)
-- **sourceEntity**: The entity where the relation originates
-- **targetEntity**: The entity where the relation points to
-- **sourceProperty**: Property name on source entity to access this relation (e.g., "posts" on User)
-- **targetProperty**: Property name on target entity to access inverse relation (e.g., "author" on Post)
-
-**Example:**
-```json
-{
-  "name": "UserPostRelation",
-  "type": "1:n",
-  "sourceEntity": "User",
-  "targetEntity": "Post",
-  "sourceProperty": "posts",
-  "targetProperty": "author"
-}
-```
-
-Additional analysis:
-- Analyze relation lifecycle (when created/deleted)
-- Identify relation-specific properties (e.g., "joinDate" on MembershipRelation)
+- **sourceEntity/targetEntity**: The connected entities
+- **sourceProperty/targetProperty**: Property names for accessing the relation from each side
+- **properties**: Relation-specific attributes (e.g., "joinDate" on MembershipRelation)
+- **lifecycle**: When the relation is created/deleted
 
 ### Step 4: Dictionary (Global Data) Identification
 
@@ -425,9 +889,9 @@ Identify system-level data:
 - System-level statistics or aggregations
 - Global configurations or settings
 
-### Output: data-concepts.json
+### Output: {module}.data-concepts.json
 
-Create `requirements/data-concepts.json`:
+Create `requirements/{module}.data-concepts.json` (replace `{module}` with actual module name from `.currentmodule`):
 
 ```json
 {
@@ -451,6 +915,175 @@ Create `requirements/data-concepts.json`:
     }
   ],
   "entities": [
+    {
+      "name": "VolcTTSCall",
+      "entityType": "api-call",
+      "description": "Records Volc TTS API call execution for tracking",
+      "properties": [
+        {
+          "name": "status",
+          "type": "string",
+          "required": true,
+          "computed": true,
+          "computation": {
+            "method": "statemachine",
+            "description": "Computed from VolcTTSEvent transitions: pending → processing → completed/failed",
+            "dependencies": ["VolcTTSEvent.status"]
+          },
+          "description": "pending | processing | completed | failed"
+        },
+        {
+          "name": "externalId",
+          "type": "string",
+          "required": true,
+          "computed": true,
+          "computation": {
+            "method": "statemachine",
+            "description": "Extracted from first VolcTTSEvent.externalId",
+            "dependencies": ["VolcTTSEvent.externalId"]
+          },
+          "description": "External task/job ID returned by the Volc TTS API service"
+        },
+        {
+          "name": "requestParams",
+          "type": "object",
+          "required": true,
+          "computed": false,
+          "description": "Text content and voice parameters sent to Volc TTS API"
+        },
+        {
+          "name": "responseData",
+          "type": "object",
+          "required": false,
+          "computed": true,
+          "computation": {
+            "method": "statemachine",
+            "description": "Extracted from VolcTTSEvent.data when status becomes completed",
+            "dependencies": ["VolcTTSEvent.data", "VolcTTSEvent.status"]
+          }
+        },
+        {
+          "name": "createdAt",
+          "type": "timestamp",
+          "required": true,
+          "computed": false
+        },
+        {
+          "name": "completedAt",
+          "type": "timestamp",
+          "required": false,
+          "computed": true,
+          "computation": {
+            "method": "statemachine",
+            "description": "Set from VolcTTSEvent.createdAt when status becomes completed or failed",
+            "dependencies": ["VolcTTSEvent.createdAt", "VolcTTSEvent.status"]
+          }
+        },
+        {
+          "name": "error",
+          "type": "object",
+          "required": false,
+          "computed": true,
+          "computation": {
+            "method": "statemachine",
+            "description": "Extracted from VolcTTSEvent.data when status becomes failed",
+            "dependencies": ["VolcTTSEvent.data", "VolcTTSEvent.status"]
+          }
+        }
+      ],
+      "referenced_in": ["INT001"],
+      "integration_source": "INT001",
+      "note": "API Call entity - status and result fields are computed via state machine based on integration events"
+    },
+    {
+      "name": "VolcTTSEvent",
+      "entityType": "api-event",
+      "description": "Events from Volc TTS service about generation completion",
+      "properties": [
+        {
+          "name": "eventType",
+          "type": "string",
+          "required": true,
+          "computed": false
+        },
+        {
+          "name": "externalId",
+          "type": "string",
+          "required": true,
+          "computed": false,
+          "description": "External task/job ID to match with the corresponding VolcTTSCall.externalId"
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "required": true,
+          "computed": false
+        },
+        {
+          "name": "createdAt",
+          "type": "timestamp",
+          "required": true,
+          "computed": false
+        },
+        {
+          "name": "data",
+          "type": "object",
+          "required": true,
+          "computed": false,
+          "description": "Event payload including audio URL"
+        }
+      ],
+      "referenced_in": ["INT001"],
+      "integration_source": "INT001",
+      "note": "Integration event entity - created by external system, NOT by user interactions"
+    },
+    {
+      "name": "Greeting",
+      "description": "User greeting message with AI-generated voice",
+      "properties": [
+        {
+          "name": "textContent",
+          "type": "string",
+          "required": true,
+          "computed": false,
+          "description": "Original text content of greeting"
+        },
+        {
+          "name": "voiceUrl",
+          "type": "string",
+          "required": false,
+          "computed": true,
+          "computation": {
+            "method": "integration-result",
+            "description": "AI-generated audio URL extracted from the LATEST successful VolcTTSCall.responseData (status='completed')",
+            "dependencies": ["VolcTTSCall.responseData", "VolcTTSCall.status"]
+          },
+          "note": "Computed from external integration - immutable, uses latest successful API call from 1:n relation"
+        }
+      ],
+      "referenced_in": ["R001", "R101"],
+      "note": "Business entity with AI-generated property - voiceUrl cannot be directly updated"
+    },
+    {
+      "name": "UserGiftProfile",
+      "entityType": "user-profile",
+      "description": "User gift balance profile - created automatically when User is created",
+      "properties": [
+        {
+          "name": "giftBalance",
+          "type": "number",
+          "required": true,
+          "computed": true,
+          "computation": {
+            "method": "aggregation",
+            "description": "Sum of all recharges minus sum of all donations",
+            "dependencies": ["RechargeRecord", "Donation"]
+          }
+        }
+      ],
+      "referenced_in": ["R001", "R101", "R102"],
+      "note": "1:1 profile entity - created with User, NOT by interactions"
+    },
     {
       "name": "Book",
       "description": "Library book entity",
@@ -524,6 +1157,31 @@ Create `requirements/data-concepts.json`:
     }
   ],
   "relations": [
+    {
+      "name": "GreetingVolcTTSCallRelation",
+      "type": "1:n",
+      "sourceEntity": "Greeting",
+      "targetEntity": "VolcTTSCall",
+      "sourceProperty": "volcTTSCalls",
+      "targetProperty": "greeting",
+      "properties": [],
+      "lifecycle": "Created each time Greeting triggers TTS generation (including retries)",
+      "referenced_in": ["INT001"],
+      "integration_source": "INT001",
+      "note": "1:n relation - one Greeting can have multiple VolcTTSCall attempts due to failures or regeneration requests"
+    },
+    {
+      "name": "UserProfileRelation",
+      "type": "1:1",
+      "sourceEntity": "User",
+      "targetEntity": "UserProfile",
+      "sourceProperty": "profile",
+      "targetProperty": "user",
+      "properties": [],
+      "lifecycle": "Created automatically when User is created",
+      "referenced_in": ["R001"],
+      "note": "1:1 profile entity - NOT created by interactions"
+    },
     {
       "name": "BorrowRecord",
       "type": "n:n",
@@ -584,10 +1242,11 @@ Create `requirements/data-concepts.json`:
 }
 ```
 
-**✅ END Task 1.3: Update `docs/STATUS.json`:**
+**✅ END Task 1.4: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
-  "currentTask": "Task 1.3",
+  "module": "<keep existing value>",
+  "currentTask": "Task 1.4",
   "completed": true
 }
 ```
@@ -595,26 +1254,91 @@ Create `requirements/data-concepts.json`:
 **📝 Commit changes:**
 ```bash
 git add .
-git commit -m "feat: Task 1.3 - Complete data concept extraction"
+git commit -m "feat: Task 1.4 - Complete data concept extraction"
 ```
 
-## Task 1.4: Interaction Design
+## Task 1.5: Interaction Design
 
-**🔄 Update `docs/STATUS.json`:**
+**🔄 Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
-  "currentTask": "Task 1.4",
+  "module": "<keep existing value>",
+  "currentTask": "Task 1.5",
   "completed": false
 }
 ```
 
 ### Design Principles
 
+**Note:** See "External System Boundary" in Core Concepts for distinguishing interactions from integrations.
+
+**Key Principles:**
 - One requirement typically maps to one interaction (sometimes multiple)
 - Interactions fulfill requirements
-- All data in interactions must reference concepts from Task 1.3
-- **CRITICAL**: Inherit all data constraints from requirements
-- **Interaction IDs must be semantic names** (e.g., "BorrowBook", "ViewAvailableBooks") not generic codes (e.g., "I001", "I002")
+- All data in interactions must reference concepts from Task 1.4
+- Inherit all data constraints from requirements
+- Interaction IDs must be semantic names (e.g., "BorrowBook", "ViewAvailableBooks") not codes (e.g., "I001")
+- ❌ If a requirement has role="System", it was incorrectly created - SKIP it, do NOT create interaction
+
+**⚠️ IMPORTANT: External Integration Interactions**
+
+If Task 1.4 includes API Call entities, design error handling interactions:
+
+**Required interactions for each `{integration}{APIname}Call` entity:**
+1. **Retry Interaction** - Allow users to retry failed API calls
+   - Role: Same as original requester
+   - Action: "retry" or "regenerate"
+   - **Creates**: NEW `{integration}{APIname}Call` entity with status='pending'
+   - **NOT updates**: Don't modify failed API call - keep it for audit trail
+   - Condition: Related business entity exists (can retry anytime)
+   - Note: Creates new API call due to 1:n relation design
+
+2. **View Status Interaction** - Allow users to check API call status
+   - Role: Same as original requester
+   - Action: "viewStatus"
+   - Reads: `{integration}{APIname}Call.status`, `{integration}{APIname}Call.error`, business entity computed result
+
+**Example:**
+```json
+{
+  "id": "RetryVolcTTSGeneration",
+  "fulfills_requirements": ["Error handling for Volc TTS generation"],
+  "type": "create",
+  "specification": {
+    "role": "User",
+    "action": "retry",
+    "conditions": ["Greeting exists"],
+    "payload": {
+      "greetingId": {
+        "type": "string",
+        "description": "ID of the greeting to regenerate TTS for",
+        "required": true
+      }
+    },
+    "data": {
+      "creates": [{
+        "target": "VolcTTSCall",
+        "description": "Create new VolcTTSCall with same requestParams from Greeting.textContent, status='pending'",
+        "dependencies": ["Greeting.textContent"]
+      }, {
+        "target": "GreetingVolcTTSCallRelation",
+        "description": "Link new VolcTTSCall to existing Greeting",
+        "dependencies": ["Greeting", "VolcTTSCall"]
+      }]
+    },
+    "dataConstraints": ["Keep previous failed VolcTTSCall for audit trail"]
+  }
+}
+```
+
+**🔴 CRITICAL: 1:1 User Profile Entity Creation**
+
+**DO NOT create 1:1 user profile entities in interactions:**
+- ❌ NEVER include 1:1 profile entities in interaction `creates` operations
+- ❌ Example WRONG: `RechargeGiftBalance` creates `UserGiftProfile`
+- ✅ CORRECT: Profile entities are created when User is created (documented in Task 1.4)
+- ✅ Interactions can UPDATE profile entity properties, but NOT CREATE the entity itself
+- These entities always exist for any User, providing default/initial values
 
 ### Interaction Specification Format
 
@@ -671,20 +1395,22 @@ The `data` field describes all data operations performed by the interaction:
 - This represents the data the user expects to receive, not dependencies for internal operations
 
 **Important Notes:**
-- Write operations should NOT include a `reads` field - use `dependencies` within each operation instead
-- Read operations should ONLY have a `reads` field - no creates/updates/deletes
-- All referenced entities/relations must exist in the data concepts from Task 1.3
+- Write operations use `dependencies` within each operation, NOT a `reads` field
+- Read operations ONLY have a `reads` field - no creates/updates/deletes
+- All referenced entities/relations must exist in Task 1.4 data concepts
+- ⚠️ DO NOT include integration event entities (e.g., `VolcTTSEvent`) in `creates` - they're created by external systems
+- ⚠️ DO NOT include 1:1 user profile entities in `creates` - they're created with User, NOT by interactions
 
-### Output: interactions-design.json
+### Output: {module}.interactions-design.json
 
-Create `requirements/interactions-design.json`:
+Create `requirements/{module}.interactions-design.json` (replace `{module}` with actual module name from `.currentmodule`):
 
 ```json
 {
   "design_metadata": {
     "timestamp": "YYYY-MM-DD HH:mm:ss",
-    "source_requirements": "requirements-analysis.json",
-    "source_data": "data-concepts.json",
+    "source_requirements": "{module}.requirements-analysis.json",
+    "source_data": "{module}.data-concepts.json",
     "version": "1.0.0"
   },
   "interactions": [
@@ -854,10 +1580,11 @@ Create `requirements/interactions-design.json`:
 }
 ```
 
-**✅ END Task 1.4: Update `docs/STATUS.json`:**
+**✅ END Task 1.5: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
-  "currentTask": "Task 1.4",
+  "module": "<keep existing value>",
+  "currentTask": "Task 1.5",
   "completed": true
 }
 ```
@@ -865,19 +1592,21 @@ Create `requirements/interactions-design.json`:
 **📝 Commit changes:**
 ```bash
 git add .
-git commit -m "feat: Task 1.4 - Complete interaction design"
+git commit -m "feat: Task 1.5 - Complete interaction design"
 ```
 
-**✅ END Task 1: Update `docs/STATUS.json`:**
+**✅ END Task 1: Update `docs/{module}.status.json` (keep existing `module` field unchanged):**
 ```json
 {
+  "module": "<keep existing value>",
   "currentTask": "Task 1",
   "completed": true,
   "completedItems": [
-    "goals-analysis.json created",
-    "requirements-analysis.json created",
-    "data-concepts.json created",
-    "interactions-design.json created"
+    "{module}.goals-analysis.json created",
+    "{module}.requirements-analysis.json created",
+    "{module}.integration.json created",
+    "{module}.data-concepts.json created",
+    "{module}.interactions-design.json created"
   ],
   "methodology": "goal-driven",
   "analysis_complete": true
@@ -891,9 +1620,10 @@ git commit -m "feat: Task 1 - Complete requirements analysis with goal-driven me
 ```
 
 **🛑 STOP: Task 1 completed. All requirements have been analyzed using the goal-driven methodology. The output includes:**
-1. **goals-analysis.json** - Refined and clarified goals from user input
-2. **requirements-analysis.json** - Complete requirement tree with read-centric derivation
-3. **data-concepts.json** - Extracted data models with dependencies
-4. **interactions-design.json** - System interactions with complete specifications
+1. **{module}.goals-analysis.json** - Refined and clarified goals from user input
+2. **{module}.requirements-analysis.json** - Complete requirement tree with read-centric derivation
+3. **{module}.integration.json** - External integration analysis and flow documentation
+4. **{module}.data-concepts.json** - Extracted data models with dependencies
+5. **{module}.interactions-design.json** - System interactions with complete specifications
 
 **Wait for user instructions before proceeding to Task 2.**