ItBuild Modules Integration

AuthProxy provides seamless integration with other ItBuild modules, enabling a unified ecosystem for business applications. This guide covers integration patterns, configuration, and best practices.

Overview

The ItBuild ecosystem consists of several interconnected modules:

• AuthProxy: Central authentication and gateway service
• TrexWallet: Cryptocurrency and transaction management
• ItBuild.Chat: Messaging and communication system
• ItBuild.CRM: Customer relationship management
• ItBuild.Core: Core business logic and project management

Integration Architecture

Configuration

Module Service Configuration

Configure ItBuild module endpoints in appsettings.json:

{
  "Config": {
    "ServiceId": 10,
    "Project": "CustomerProject",
    "Domain": "app.customer.com",
    "CoreApiKey": "generated_secure_key",
    "Modules": {
      "Wallet": "http://wallet-service:80",
      "Chat": "http://chat-service:80",
      "CRM": "http://crm-service:80",
      "Core": "http://core-service:80"
    }
  }
}

Key Parameters:

Parameter	Purpose	Example
ServiceId	Service instance id for TimeTick (AuthProxy: 10-19)	10
Domain	Your verified project domain	"app.customer.com"
CoreApiKey	Internal API authentication key	Generated securely
Modules.*	Internal service URLs	"http://service:80"

Routing Configuration

AuthProxy routes requests to modules based on the route_map table. Authorization on a route is controlled by the flags bitmask (RouteFlags), not by a free-form scopes column.

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

RouteFlags (subset most relevant to module integrators):

Flag	Bit	Meaning
NoRateLimit	1	Disable per-route rate limiting.
AllReferers	2	Allow CORS from any verified app (paired with AppAuthAndCORS, see below).
AppAuthAndCORS	4	Route is reachable from external app domains; works only together with AppFlag.AppAuthAndCORS on the calling user_app.
ScopeCheck	8	Require route.path to be present in user.scopes for the active session.
NoAuth	16	Anonymous endpoint.
NoLoginForm	32	Don't substitute login form on missing auth.
CheckAppId	64	If app_id > 0 in the query, validate ownership and inject X-AppId.
CheckPubKey	256	Allow pkey-based call (header pkey); inject X-Pkey-Crm.
GeoEnrich	512	Inject X-Country from the GeoIp cache.
BuiltIn	1024	Internal AuthProxy controller (not proxied).
InternalApi	2048	Inter-module API: private IP allowlist + X-API-Key.

Scope semantics: a session's user.scopes is a list of route paths the user is allowed to hit. When ScopeCheck is set, AuthProxy looks for route.path inside user.scopes. There is no free-form read write admin string — the unit of authorisation is a route path, not a custom verb.

Configuration via Admin Panel:

1. Navigate to /ProxyAdmin/RouteMap.
2. Add new route:
   • Path: /wallet/v1 (URL prefix).
   • Address: http://wallet-service:80 (internal service).
   • Flags: pick the RouteFlags bits required (e.g. tick ScopeCheck for protected routes, NoAuth for public).
   • Tag: TrexWallet (for monitoring).

Module Communication

ApiResponse Format

All ItBuild modules use a single response envelope, ApiResponse<T>. JSON layout:

{
  "id": 0,
  "result": { /* T or scalar; null on error */ },
  "error": null
}

• id is a plain integer (default 0). jsonrpc is omitted on regular REST and is only present for /mcp JSON-RPC responses.
• result and error are mutually exclusive: success ⇒ result filled, error: null; failure ⇒ result: null, error: { code: int, message: string }.
• error.code is an integer drawn from ApiError / ApiGateError / module-specific error classes. Codes are positive integers per module range, with a few platform-wide negatives (e.g. -11001 for gateway-level failures and -31xxx for ApiResponse<T> framework errors).

Success Response:

{
  "id": 0,
  "result": {
    "timetick": 17234567890001,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "error": null
}

Error Response:

{
  "id": 0,
  "result": null,
  "error": {
    "code": 1102,
    "message": "The account is not in the system"
  }
}

The /mcp endpoint speaks JSON-RPC 2.0 and uses the standard -32xxx error codes alongside its own tools/call envelope; see MCP Protocol.

C# Implementation

Automatic Conversion:

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Explicit Error Handling:

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Shared Authentication

Single Sign-On (SSO)

AuthProxy provides SSO across all ItBuild modules. Identity is propagated through dedicated headers — there is no X-User-Id or X-UserId header in the platform.

1. User logs in via AuthProxy → session cookie sid=… created.
2. User accesses module (e.g., /wallet/v1/balance).
3. AuthProxy validates session → resolves the active session and derived context.
4. AuthProxy forwards request with the following injected headers (only those relevant to the route are added):

Header	When set	Meaning
X-Project	always	Project numeric id (Config.Project).
X-Crm	session present	CRM identifier of the authenticated user.
X-Scopes	session present	Comma-separated list of route paths the user is allowed to call.
X-KeyType	session present	LoginMethod enum value (Cookie / AppLogin / Mcp / Pkey / …).
X-AppId	AppLogin session OR pkey + CheckAppId route flag	Application identity.
X-MCP-App-Id	MCP login	Application bound to the MCP session.
X-Pkey-Crm	pkey path	CRM resolved from the public key (header pkey).
X-Country	route flag GeoEnrich	ISO country code from the GeoIp cache.
X-SignResult	sign verification path	valid when the cookie signature was verified.

The legacy headers X-User-Id and X-UserId are not part of the contract and are not produced by ReverseProxyMiddleware.

5. Module processes request → uses X-Crm (and X-AppId, etc.) from headers.

Request Flow:

Inter-Module Communication

Modules can call each other via HTTP + ApiResponse:

Example: Chat calling CRM

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Registration in Startup:

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

AuthProxy as Reverse Proxy

AuthProxy acts as the single entry point for all client requests:

Request Processing Pipeline

1. ApiPathMiddleware - Resolves route from route_map
2. CorsMiddleware - Validates CORS policy
3. ResponseCaching - Checks cache
4. FileCacheMiddleware - Serves static files
5. ReversProxyMiddleware - Authenticates + proxies to module
6. Controllers - AuthProxy's own endpoints

Example Route Resolution:

Client Request: GET https://app.customer.com/wallet/v1/balance
                ↓
ApiPathMiddleware: Resolve route_map by longest prefix on `path`
                ↓
Found: address = 'http://wallet-service:80', flags = ScopeCheck
                ↓
ReversProxyMiddleware:
  - Validate session (cookie sid=…)
  - Resolve crm_id, scopes, login_type
  - Apply flags: ScopeCheck verifies '/wallet/v1' is in user.scopes
  - Forward: GET http://wallet-service:80/wallet/v1/balance
  - Inject: X-Crm, X-Scopes, X-KeyType, X-Project (+ X-AppId / X-Country / X-Pkey-Crm where applicable)
                ↓
Module Response: ApiResponse<Balance>
                ↓
Return to Client

Scope-Based Authorization

A user's session carries scopes — a list of route paths they are allowed to call. Routes opt in by setting the ScopeCheck flag.

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Scope Validation (real semantics):

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

The user.scopes string is built from the session-level scope assignments (admin / wallet / chat module), and editing it through /ProxyAdmin/Sessions propagates to subsequent requests via the KeysAndApps cache.

Database Independence

CRITICAL: Each module has a separate database:

• project123_authproxy - AuthProxy data (users, sessions, keys)
• project123_wallet - TrexWallet data (wallets, transactions)
• project123_chat - Chat data (messages, channels)
• project123_crm - CRM data (customers, contacts)

NO shared tables between modules. All communication via APIs.

Why Separate Databases?

1. Isolation - Module failures don't cascade
2. Scalability - Scale databases independently
3. Security - Module can't access other module data directly
4. Deployment - Update module without affecting others

Shared Libraries

ItBuild.Shared

All modules reference ItBuild.Shared library:

Core Components:

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Best Practices

1. Use ApiResponse Everywhere

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

2. Use TimeTick for IDs

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

3. Null Semantics for Updates

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

4. Module Communication via Config

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Troubleshooting

"Module communication failed"

Check:

1. Route configured in route_map table
2. Module address uses Docker network name (not localhost)
3. Module is running (docker ps)
4. Firewall allows traffic

Debug:

# From AuthProxy container
docker exec -it project123-authproxy sh
wget http://wallet-service:80/health

"Unauthorized" on module endpoint

Check:

1. Session cookie present in request
2. Route scopes match user scopes
3. Session not expired
4. User has required permissions

"ApiResponse null"

Check:

1. Module returns correct JSON format
2. Content-Type is application/json
3. No serialization errors

Related Documentation

• AuthProxy Architecture
• Authentication API
• Reverse Proxy
• Admin Dashboard