Debugging Guide

This guide covers setting up a local debugging environment for ThunderID's backend, Gate app, Console app, and React SDK sample application.

Introduction

ThunderID consists of the following components:

Component	Description	Port
Backend	Go-based API server	8090
Gate App	React-based authentication gateway	5190
Console App	React-based developer console	5191
React SDK Sample	Sample app demonstrating OAuth integration	3000

This guide focuses on local development and debugging with SQLite for database storage.

Prerequisites

Required

• Go (v1.26+)
• Node.js (20+)
• pnpm (v10)
• Delve (Go debugger)

  go install github.com/go-delve/delve/cmd/dlv@latest

• VS Code with the Go extension
• DBeaver (database viewer)
• Google Chrome browser

Optional

• yq — YAML parser for better config parsing

  brew install yq

Start ThunderID for Debugging

Step 1: Configure the Server

Add the frontend development origins to backend/cmd/server/config/resources/server_configs/cors.yaml so the apps can call the backend:

name: cors
value:
  allowedOrigins:
    - "https://localhost:3000"
    - "https://localhost:5190"
    - "https://localhost:5191"

Gate client port — add this to backend/cmd/server/deployment.yaml (so the backend knows where to redirect for auth):

gate_client:
  port: 5190

Step 2: Seed Data

Open a terminal and switch to the ThunderID root directory:

cd <repo-root>

Seed the initial data (one-time only) with the in-process bootstrap subcommand. It creates the default resources directly through the service layer, so no running server or security bypass is required:

PUBLIC_URL="https://localhost:8090" \
  go run -C backend/cmd/server . bootstrap \
  --console-redirect-uris "https://localhost:5191/console"

Stop the backend by pressing Ctrl + C.

Step 3: Start the Backend in Debug Mode

make debug_backend

Step 4: Start the Frontend

In a new terminal:

make run_frontend

Step 5: Start the Sample App (Optional)

In a new terminal, navigate to the sample app:

cd <repo-root>/samples/apps/react-sdk-sample

Generate TLS certificates:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -days 365 \
  -keyout server.key -out server.cert \
  -subj "/O=WSO2/OU=ThunderID/CN=localhost"

Run the sample app:

npm run dev

Connect Debuggers

Connect to Console App (Browser DevTools)

1. Open https://localhost:5191/console in Chrome
2. Open DevTools (Cmd+Option+I on macOS, F12 on Windows/Linux)
3. Navigate to Sources → top → localhost:5191 → console → src
4. Click on a line number to set a breakpoint
5. When that line executes, Chrome pauses execution and lets you inspect variables

Connect to Backend (VS Code)

1. Open the ThunderID repository in VS Code
2. Go to Run and Debug view (Cmd+Shift+D)
3. Select "Connect to server" from the dropdown
4. Click the green Play button or press F5
5. Switch to the Debug Console (Cmd+Shift+Y) to view output

Setting breakpoints:

• Open any Go file
• Click in the gutter to the left of a line number to add a breakpoint (red dot)
• When that line executes, VS Code pauses execution

Connect DBeaver to View Database Tables

1. Open DBeaver
2. Open the New Database Connection wizard (Ctrl+Shift+N)
3. Select SQLite and click Next
4. Set the path to one of the database files:

Database	Path
User DB	<repo-root>/backend/cmd/server/database/userdb.db
Runtime DB	<repo-root>/backend/cmd/server/database/runtimedb.db
Config DB	<repo-root>/backend/cmd/server/database/configdb.db

5. Click Test Connection to verify, then click Finish
6. Repeat for the other two databases

Debug with Local SDK Changes

When developing or testing against unreleased SDK changes, you can point the product frontend at a local build instead of the published npm packages.

The JavaScript SDKs live in a separate repository. Clone it if you haven't already, then install dependencies:

git clone https://github.com/thunder-id/javascript-sdks
cd javascript-sdks
pnpm install

Generate Local File Paths

Run the symlink script to build the SDK packages and print the file: path entries to paste into the product:

pnpm symlink

The script outputs multiple blocks — copy the overrides block.

Apply and Install

Paste the copied overrides into pnpm-workspace.yaml at the repository root under overrides:, then run pnpm install from the repository root to link the local packages:

cd <repo-root>
pnpm install

Restart the frontend dev server for the changes to take effect. To revert, remove the overrides entries and run pnpm install again.

Sample Debug Scenario: User Creation

This walks through debugging the user creation flow from the UI to database storage.

1. Set Console App Breakpoints

In Chrome DevTools, open:

• features/users/api/useCreateUser.ts — set a breakpoint at const serverUrl: string = getServerUrl();

2. Set Backend Breakpoints

In VS Code, open these files and set breakpoints:

• backend/internal/user/handler.go — at the beginning of HandleUserPostRequest
• backend/internal/user/service.go — at the beginning of CreateUser
• backend/internal/user/store.go — at the beginning of CreateUser

3. Trigger the Flow

1. Navigate to https://localhost:5191/console
2. Log in with the admin credentials configured during setup (default: admin / admin)
3. Go to Users section
4. Click Add User
5. Select User Type: Person
6. Fill in:
   • Username: john.doe
   • Email: john.doe@example.com
   • Password: Test@1234
7. Click Create User

4. Debug the Flow

• Chrome pauses at the frontend breakpoint — inspect variables and step through the API call
• Once the API call is made, VS Code pauses at the backend breakpoints
• Use the Variables panel to inspect request data
• Step through the code (F10 step over, F11 step into, F5 continue)
• After continuing through the flow, the user is saved to the database

5. Verify in Database

Open DBeaver and view the User table in the User DB to confirm the new user was created.