Skip to content

Instantly share code, notes, and snippets.

@decagondev

decagondev/USER-FLOW.md

Created April 11, 2025 20:15
Show Gist options
  • Save decagondev/f5f233f86a149900d2add62e0d50959c to your computer and use it in GitHub Desktop.
Save decagondev/f5f233f86a149900d2add62e0d50959c to your computer and use it in GitHub Desktop.
Download ZIP
Raw
USER-FLOW.md

Utility Profit Consolidated Workflow API - User Flow

This document illustrates the flow of data through the Utility Profit Consolidated Workflow API, from initial user input to final consolidated output. The diagrams and explanations provide a visual and textual representation of each step in the process.

High-Level Overview

graph TD
    A[User/Client] --> B[API Endpoint]
    B --> C{Validation}
    C -- Valid --> D[Create User]
    C -- Invalid --> E[Return Error]
    D --> F[Create Address]
    F --> G[Create Partner Profile]
    G --> H[Process Utility Services]
    H --> I[Send BCC Reminder]
    I --> J[Update Relationships]
    J --> K[Consolidate Data]
    K --> A

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style E fill:#ffd1d1,stroke:#333,stroke-width:1px,color:#000
    style K fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style F fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style G fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style H fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style I fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style J fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Detailed User Flow

1. Request Submission and Validation

sequenceDiagram
    participant Client
    participant API
    participant Validator
    
    Client->>API: POST /utility-workflow
    API->>Validator: Validate Request Data
    Validator-->>API: Validation Result
    
    alt Valid Request
        API->>API: Proceed to User Creation
    else Invalid Request
        API-->>Client: Return 400 Bad Request
    end
Loading

Explanation:

  • The client submits a POST request to the /utility-workflow endpoint with user information, address details, partner information, and utility types.
  • The API validates the request data using Pydantic models.
  • If validation fails, the API returns a 400 Bad Request with error details.
  • If validation succeeds, the API proceeds to the next step.

2. Resource Creation Flow

graph TD
    A[Valid Request] --> B[User Created]
    B --> C[Address Created]
    C --> D[Partner Profile Created]
    D --> E[Utility Services Processing]
    
    subgraph UserCreation[User Creation]
        direction TB
        U1[Extract User Info] --> U2[Format User Data]
        U2 --> U3[Call Utility Profit API]
        U3 --> U4[Store User ID]
        style U1 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style U2 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style U3 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style U4 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    end

    subgraph AddressCreation[Address Creation]
        direction TB
        A1[Extract Address Info] --> A2[Format Address Data]
        A2 --> A3[Call Utility Profit API]
        A3 --> A4[Store Address ID]
        style A1 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style A2 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style A3 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style A4 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    end

    subgraph PartnerCreation[Partner Profile Creation]
        direction TB
        P1[Extract Partner Info] --> P2[Format Partner Data]
        P2 --> P3[Call Utility Profit API]
        P3 --> P4[Store Profile ID]
        style P1 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style P2 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style P3 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
        style P4 fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    end

    A --> UserCreation
    B --> AddressCreation
    C --> PartnerCreation

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff

    %% Subgraph styling
    classDef subgraphStyle fill:#1a1a1a,stroke:#333,stroke-width:1px
    class UserCreation,AddressCreation,PartnerCreation subgraphStyle
Loading

Explanation:

  • The API creates three primary resources in sequence: user, address, and partner profile.
  • For each resource, the API extracts relevant information from the request, formats it according to the external API requirements, and makes the appropriate API call.
  • The IDs returned from each creation step are stored for use in subsequent steps.

3. Utility Service Processing

graph TD
    A[Partner Profile Created] --> B[Process Utility Service]
    B --> C[Form Structure Researched]
    C --> D[Agent Started]
    D --> E[Address Response Submitted]
    E --> F[Utility Type Created]
    F --> G[Activation Created]
    G --> H[Activation Details Retrieved]
    H --> I[Service Result Stored]
    I --> J[Proceed to Notifications]
    I --> A

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style J fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style F fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style G fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style H fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style I fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Explanation:

  • For each utility type in the request, the API processes the utility service through several steps.
  • The process includes researching the form structure, starting a form filling agent, submitting address information, creating required utility types, creating transfer activations, and retrieving activation details.
  • The results from each utility service processing are stored for later consolidation.

4. Notification and Relationship Updates

graph TD
    A[All Utilities Processed] --> B[User Data Prepared]
    B --> C[BCC Reminder Sent]
    C --> D[User Partners Updated]
    D --> E[Required Utility Types Updated]
    E --> F[Data Consolidation]

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style F fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Explanation:

  • After processing all utility services, the API prepares user data for notifications.
  • The API sends a BCC reminder for all activations.
  • The API updates the user-partner relationships and required utility types.
  • These steps ensure that all necessary notifications are sent and relationships are properly established.

5. Data Consolidation and Response

graph TD
    A[All Steps Completed] --> B[User Data Consolidated]
    B --> C[Address Data Consolidated]
    C --> D[Partner Profile Data Consolidated]
    D --> E[Utility Services Data Consolidated]
    E --> F[Final Response Formatted]
    F --> G[Response Returned to Client]

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style G fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style F fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Explanation:

  • The API consolidates all the data collected throughout the workflow into a single response.
  • The consolidated data includes user information, address details, partner profile information, and utility service details.
  • The API formats the final response according to the UtilityServiceResponse model.
  • The API returns the consolidated response to the client.

Complete End-to-End Flow

sequenceDiagram
    participant Client
    participant API
    participant UtilityProfit
    participant FormFill
    
    Client->>API: POST /utility-workflow
    API->>API: Validate Request
    
    API->>UtilityProfit: Create User
    UtilityProfit-->>API: User Created (ID: user123)
    
    API->>UtilityProfit: Create Address
    UtilityProfit-->>API: Address Created (ID: addr123)
    
    API->>UtilityProfit: Create Partner Profile
    UtilityProfit-->>API: Partner Profile Created (ID: profile123)
    
    loop For Each Utility Type
        API->>FormFill: Research Form
        FormFill-->>API: Form Structure
        
        API->>FormFill: Start Form Filling Agent
        FormFill-->>API: Agent Started (session_id: session123)
        
        API->>FormFill: Submit Address Response
        FormFill-->>API: Response Submitted
        
        API->>UtilityProfit: Create Required Utility Type
        UtilityProfit-->>API: Utility Type Created
        
        API->>UtilityProfit: Create Transfer Activation
        UtilityProfit-->>API: Activation Created (ID: activation123)
        
        API->>UtilityProfit: Get Activation Details
        UtilityProfit-->>API: Activation Details
    end
    
    API->>UtilityProfit: Send BCC Reminder
    UtilityProfit-->>API: Reminder Sent
    
    API->>UtilityProfit: Update User Partners
    UtilityProfit-->>API: Partners Updated
    
    API->>UtilityProfit: Update Required Utility Types
    UtilityProfit-->>API: Utility Types Updated
    
    API->>API: Consolidate Data
    API-->>Client: Return Consolidated Response
Loading

Explanation:

  • This sequence diagram shows the complete end-to-end flow of the Utility Profit Consolidated Workflow API.
  • It illustrates the interactions between the client, the API, the Utility Profit system, and the Form Fill system.
  • The diagram shows how data flows through the system and how the API orchestrates the entire workflow.
  • The final step is the consolidation of all data and the return of the consolidated response to the client.

Data Transformation Flow

graph LR
    A[Raw Request Data] --> B[Validated Data]
    B --> C[Utility Profit Data]
    B --> D[Form Fill Data]
    C --> E[External API Responses]
    D --> E
    E --> F[Processed Data]
    F --> G[Consolidated Response]
    G --> H[Final Response]

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style H fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style C fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style F fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style G fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Explanation:

  • This diagram illustrates how data is transformed throughout the workflow.
  • Raw request data is first extracted and validated.
  • The validated data is then transformed into the format required by each external API.
  • After receiving responses from the external APIs, the API extracts the relevant data.
  • The extracted data is consolidated into a single response.
  • The consolidated response is formatted for the client and returned.

Error Handling Flow

graph TD
    A[API Request] --> B{Process Request}
    B -->|Success| C[Return Success Response]
    B -->|Error| D{Error Type}
    D --> E[Return 400 Bad Request]
    D --> F[Return 401 Unauthorized]
    D --> G[Return 403 Forbidden]
    D --> H[Return 404 Not Found]
    D --> I[Return 502 Bad Gateway]
    D --> J[Return 500 Internal Server Error]
    
    E --> K[Include Error Details]
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    K --> L[Log Error]
    L --> M[Return Error Response]

    %% Node styling
    style A fill:#ffb6c1,stroke:#333,stroke-width:1px,color:#000
    style C fill:#e6e6fa,stroke:#333,stroke-width:1px,color:#000
    style M fill:#ffd1d1,stroke:#333,stroke-width:1px,color:#000
    style B fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style D fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style E fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style F fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style G fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style H fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style I fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style J fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style K fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
    style L fill:#2b2b2b,stroke:#333,stroke-width:1px,color:#fff
Loading

Explanation:

  • This diagram illustrates the error handling flow in the API.
  • The API attempts to process each request.
  • If an error occurs, the API determines the type of error.
  • Based on the error type, the API returns an appropriate HTTP status code.
  • The API includes detailed error information in the response.
  • The API logs the error for debugging purposes.
  • The API returns the error response to the client.

Conclusion

The Utility Profit Consolidated Workflow API implements a comprehensive workflow that handles the entire utility service registration process from start to finish. The diagrams and explanations in this document provide a visual and textual representation of the data flow through the system, from initial user input to final consolidated output.

By understanding this flow, developers can better appreciate the complexity and orchestration involved in the API, and users can better understand how their data is processed and transformed throughout the workflow.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment