Architecture Overview

AuthProxy is designed as a comprehensive security gateway that serves multiple critical functions in the ItBuild ecosystem. It acts as the primary entry point for all client requests, ensuring secure access to protected resources while providing authentication, reverse proxy, and web server capabilities.

ItBuild Platform Context

AuthProxy is a core component of the ItBuild Platform - a comprehensive system for creating multi-tenant PWA applications.

Platform Architecture

Multi-Tenant Key Concepts

1. Domain-Bound Modules

Every build is tied to your verified domain. Modules validate the domain on startup - if the request domain doesn't match the licensed domain, the module won't function. This ensures:

• Modules only run on authorized domains
• Secure inter-module communication
• Build tracking per project

2. Database Independence

Each module has separate database:

• project123_authproxy - AuthProxy data (users, sessions, keys)
• project123_wallet - TrexWallet data (wallets, transactions)
• project123_chat - Chat data (messages, channels)
• project123_core - Customer's Core module data

NO shared tables between modules. Communication only via APIs.

3. Two Frontend Systems

PWA Applications (Separate repositories):

• AuthProxy PWA (Preact, < 200KB) - First load is CRITICAL
  • Repository: /apg.pwa
  • Tech: Preact 10.25, TypeScript, Vite
  • Deployed to: AuthProxy/wwwroot/
• Other Modules PWA (React, < 500KB) - Feature-rich
  • Repositories: /trexwallet.pwa, /chat.pwa, etc.
  • Tech: React 19, TypeScript, Vite, Feature-Sliced Design
  • Deployed to: AuthProxy/wwwroot/wallet/, /chat/, etc.

Admin Pages (Razor Pages):

• Location: AuthProxy/Pages/ProxyAdmin/
• Server-rendered C# pages
• jQuery + DataTables (minimal JavaScript)
• This is backend work, not frontend

4. Port Management

Shared development environment:

• Customer port range: 8001-8999 — each customer project gets its own.
• Assignment: automatic from database.
• Edge forwarding: public customer port → project VM customer port.
• The platform team's own dev stand is separate and is not used for customer testing.

The assigned port is visible in project administration and deployment logs.

PROD Environment:

• Standard ports: 80 (HTTP), 443 (HTTPS)
• Customer's infrastructure or ItBuild-managed

5. Docker Deployment

Base Image Strategy (not storing container versions):

# itbuild/dotnet-base:10.0 (single image for all)
FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine
WORKDIR /app
ENTRYPOINT ["dotnet"]

Runtime Mounting:

docker run -d \
  --name project123-authproxy \
  -p 8001:80 \
  -v /projects/123/AuthProxy/1.2.0:/app:ro \
  -v /projects/123/configs/authproxy.json:/app/appsettings.json:ro \
  itbuild/dotnet-base:10.0 \
  AuthProxy.dll

Benefits:

• Easy rollback (mount previous version)
• Storage efficient (one base image)
• Fast deployment (no image build)

Standard Modules vs Core Module

Standard Modules (ItBuild maintains):

Module	Purpose	Key Features
AuthProxy	Web server, auth, proxy	14 auth methods, file service, SSE, rate limiting, embedded STUN, inbound email
TrexWallet	Crypto wallets	6 blockchain scanners + Acquiring sidecar, hybrid Payment Gateway, multi-wallet lifecycle
TrexWallet.Markets	Rate aggregation	9 sources (Binance, Kraken, WhiteBit, Bitfinex, Huobi, Yobit, Bybit, Bestchange, CoinGecko)
Chat	Communications hub	SMS (5 providers), Email, Telegram, files, WebRTC calls (in chat_mess), widget messages
CRM	Customer management	Cards, referrals, user_exid_flags Verified / ManuallyAdded

AuthProxy Authentication Methods:

Category	Methods
Hardware / software keys	PassKey, Fido2Key, UserKey
OTP	Phone, Email
Magic links	Email-only login
OAuth	Google, Apple, Microsoft, GitHub, Facebook, VK, Discord, Telegram
Federation v2	Browser federation through verified partner project
Service / programmatic	AppLogin, MCP (Basic / Verified / App)

• Pre-built and tested
• Maintained by ItBuild
• You integrate via REST API

Core Module (Customer owns):

• Your business logic
• Full source code access
• Your Git repository
• You control development
• Integrates with standard modules

Learn more: ItBuild Platform Documentation

System Architecture

AuthProxy follows a modular, middleware-based architecture that processes requests through a carefully ordered pipeline:

Core Components

1. Security Gateway

• Multi-factor authentication (FIDO2, passwords, social login)
• Session management with secure cookies
• Rate limiting and abuse prevention
• CORS policy enforcement

2. Reverse Proxy

• Dynamic routing based on database configuration
• Load balancing capabilities
• SSL termination
• Request forwarding to internal microservices

3. Web Server

• PWA application hosting
• Static file serving with memory caching
• SPA routing support
• Performance optimization

4. Administrative Interface

• Razor Pages-based admin panel
• User management
• System monitoring
• Configuration management

Middleware Pipeline

The request processing follows this specific order:

1. API Path Middleware: Determines routing based on request path and database configuration
2. CORS Middleware: Handles cross-origin request security for browsers
3. Response Caching: Caches HTTP responses based on headers
4. File Cache Middleware: Serves static files from memory cache
5. Reverse Proxy Middleware: Forwards authenticated requests to internal services
6. API Controllers: Handles authentication and management operations
7. Razor Pages: Serves administrative interface

Database Integration

AuthProxy supports multiple database engines through the DbCore abstraction:

Database	Class	Use Case
SQL Server	DbCore	Production with full TrexWallet support
SQLite	DbCoreSQLite	Standalone mode, edge deployment, testing
PostgreSQL	DbCorePostgres	Open source alternative

All SQL queries use ANSI-compatible syntax for cross-database compatibility.

Key Tables

• apguser: User accounts and credentials
• user_key: Authentication keys (FIDO2, passwords, API keys)
• login_log: Authentication attempt logging
• sign_log: Transaction signature logging
• route_map: API routing configuration
• app_access: Application access control

Service Integration

AuthProxy integrates with other ItBuild modules:

• TrexWallet: Cryptocurrency wallet operations
• ItBuild.Chat: Messaging and notifications
• ItBuild.CRM: User data management
• External Providers: Google OAuth, Telegram authentication

Security Model

The security architecture implements multiple layers of protection:

• Transport Security: HTTPS enforcement for all communications
• Authentication: Multi-factor authentication with FIDO2 support
• Authorization: Role-based access control
• Audit Logging: Comprehensive logging of all security events
• Rate Limiting: Protection against abuse and DoS attacks

Deployment Architecture

AuthProxy is designed for containerized deployment:

• Docker container support
• Environment-based configuration
• Telemetry and monitoring with OpenTelemetry

Horizontal Scaling with Session Locality

AuthProxy uses a unique approach to horizontal scaling - session locality without synchronization:

main.app.com (DNS Round Robin) → IP1, IP2, IP3
         ↓
Frontend probes p1.app.com, p2.app.com, p3.app.com in parallel
         ↓
Client switches to fastest responding proxy
         ↓
Session is LOCAL to this proxy (no Redis/shared state)

Benefits:

• No synchronization overhead between instances
• User "sticks" to nearest/fastest proxy
• Each AuthProxy instance is fully independent
• Simple deployment without shared state infrastructure

Audit Logging

All authentication attempts logged in login_log table:

Field	Description
IP Address	Client IP with geolocation
Device Info	User agent string
Screen Resolution	Browser viewport size
Device GUID	Fingerprint for device identification
Timezone	Client timezone
Browser Language	Preferred language

Rate Limiting

Several separate rate limiting layers protect against abuse, all using fixed-window counters:

• Per Connection — limits single TCP connection throughput (default: 10 RPS).
• Per IP — limits aggregate traffic from a single IP across all connections (configurable, default: disabled).
• Per Session — fixed-window counter for authenticated users (RateLimitWindowSeconds).
• Per Public Key — limits app-to-app API calls.
• Per Bandwidth — byte-level throttling for file transfers.

Performance

Load tested with k6 against nginx baseline (February 2026):

Metric	Value
Peak throughput (500 VU)	14,000+ RPS
Proxy overhead vs nginx (p95)	+1.8ms
Max concurrent users tested	500 (0% errors)
Mixed workload (100 VU, 5 min)	1,935 RPS, p95 < 2ms

Sessions use lock-free ConcurrentDictionary for O(1) lookup without contention. Connection pool supports 256 concurrent connections per backend module.