Mastering UML Sequence Diagrams with VPasCode: Secure Auth & JWT

System architecture is the backbone of any robust software application, and visualizing the flow of data is critical for developers and stakeholders alike. Sequence diagrams are among the most powerful tools in a software engineer’s arsenal, providing a dynamic view of interactions between objects over time. In this tutorial, we will dive deep into the architecture of a secure user authentication system using JSON Web Tokens (JWT). We will demonstrate how to model this complex logic using PlantUML within the VPasCode environment, transforming abstract requirements into a clear, executable visual model.

Understanding the System Components

Before writing a single line of code, we must define the “actors” and “participants” of our system. In the architecture of a modern web application, a typical login process involves four distinct entities:

  • User (Actor): The human entity initiating the request. In sequence diagrams, this is represented by a stick figure.
  • Frontend App (Participant): The client-side application (e.g., React, Angular, or a mobile app) that collects user input and communicates with the server.
  • Auth Service (Participant): The backend microservice responsible for business logic, security validation, and token generation.
  • User Database (Database): The persistent storage layer where user credentials are securely stored.

Modeling the Interaction Flow

The sequence diagram maps the chronological order of these interactions. The flow generally begins with the user attempting to access the system and ends with the system either granting or denying access.

1. The Authentication Request

The process starts when the User enters their credentials into the Frontend App. This is modeled as a synchronous message: User -> Frontend: Enter credentials. Once the user clicks “Login,” the Frontend constructs an HTTP request and sends it to the Auth Service via a POST /login request. This step moves the data from the client to the server.

2. Database Verification

Upon receiving the request, the Auth Service must verify the user’s identity. It sends a query to the User Database: Auth -> DB: Query user credentials. The database performs a lookup and returns the stored user data to the Auth Service. Note the use of a dashed arrow (return message) to indicate that data is flowing back to the requester.

3. Local Validation

Once the Auth Service receives the data, it performs a local check. It compares the password provided in the request against the hashed password retrieved from the database. This internal logic is often represented as a self-referencing message: Auth --> Auth: Validate password.

Handling Logic Branches with ‘alt’ Frames

Real-world systems must handle success and failure scenarios. In PlantUML, the alt (alternative) block is used to model conditional logic, creating a branching path in the diagram.

The Success Path: Valid Credentials

If the password validation is successful, the system enters the first branch of the alt block. The Auth Service generates a JWT token—a secure, stateless token that proves the user’s identity. This token is returned to the Frontend, which then displays a “Login Successful” message to the User. The JWT token is crucial as it allows the user to access subsequent resources without logging in again.

The Failure Path: Invalid Credentials

If the password does not match, the system enters the else block. The Auth Service sends an error message back to the Frontend. The Frontend then displays this error to the User, preventing access to the system. This ensures that the application fails securely without exposing sensitive information about the database or user existence.

Using VPasCode for Diagram-as-Code

VPasCode (Visual Paradigm as Code) empowers developers to write these diagrams using text rather than drag-and-drop tools. The workflow is efficient and version-control friendly:

  1. Write Code: Define the participants and messages using simple text syntax.
  2. AI Integration: Use the built-in AI generator to prompt the system (e.g., “Show me a sequence diagram for user login”) to generate a starting template.
  3. Iterate: Adjust timing, add error handling, or modify participants directly in the code editor.
  4. Visualize: The diagram renders instantly on the right-hand side, providing immediate feedback.

By embedding this live diagram into your technical documentation (such as an authentication guide), you ensure that your architecture documentation remains up-to-date and visually accurate. This approach bridges the gap between abstract requirements and concrete system implementation.