ItBuild Platform Overview

ItBuild is a multi-tenant platform for rapid development and deployment of business applications. This document explains the platform architecture, key concepts, and how everything works together.

Platform Architecture

graph TB
    subgraph "ItBuild Platform"
    A[ItBuild.app] --> B[Projects Database]
    A --> C[License Generator]
    A --> D[Build Orchestrator]
    A --> E[File Server]

    D --> F[Build Server]
    F --> G[Binary Storage]

    E --> H[/projects/123/]
    H --> I[configs/]
    H --> J[AuthProxy/1.0.0/]
    H --> K[TrexWallet/1.0.0/]
    end

    subgraph "Customer Project"
    L[VM: 10.0.X.Y]
    M[Docker: AuthProxy :8001]
    N[Docker: TrexWallet]
    O[Docker: Chat]
    P[SQL Server]

    L --> M
    L --> N
    L --> O
    L --> P

    M --> Q[wwwroot/]
    Q --> R[PWA: apg.pwa]
    Q --> S[PWA: trexwallet.pwa]
    end

    subgraph "Internet"
    T[dev.itbuild.app:8001]
    U[app.customer.com]
    end

    H --> M
    H --> N
    T --> M
    U --> M

Core Concepts

1. Multi-Tenant Architecture

What is Multi-Tenant?

One platform serves multiple customers (tenants), each with:

• Isolated data - Your database, your data
• Own domain - Your brand (e.g., app.yourcompany.com)
• Custom configuration - Your business rules
• Separate resources - Dedicated or shared VM

Benefits:

• Lower costs (shared infrastructure)
• Faster updates (one codebase, many customers)
• Proven reliability (battle-tested by all tenants)

2. Domain-Bound Licensing

Every build of every tier is compiled with an embedded domain identifier. Modules only function on the embedded domain or on platform development sentinels (localhost, dev.itbuild.app). This is a core platform enforcement mechanism applied uniformly to all license tiers.

How it works:

1. You specify the deployment domain at build request time
2. Modules are built with that domain embedded into the binary
3. Modules only function on the embedded domain
4. Domain change requires a new build

Tier difference is in domain verification:

• Personal Free — any domain accepted (custom, localhost, dev sentinel), no DNS verification
• Startup / Standalone / Subscription — DNS-based ownership verification required before build

Benefits:

• Prevents unauthorized deployment
• Ensures module compatibility within your project
• Enables secure inter-module communication

See Licensing for the four license tiers (Personal Free, Startup, Business Standalone, Business Subscription).

3. Standard Modules vs Core Module

Standard Modules (ItBuild Team Maintains)

Module	Purpose	Key Features
AuthProxy	Web server, authentication, proxy	14 auth methods, file service, SSE/Webhooks, MCP server, rate limiting
TrexWallet	Crypto wallets, transactions	6 blockchain scanners, exchange rates, batch ops, events API
Chat	Communications hub	SMS (5 providers), Email, Telegram, files, tasks, events API
CRM	Customer management	Cards, referrals, external IDs

Access: Pre-built binaries with embedded license. You integrate via REST API.

AuthProxy - 14 Authentication Methods

Category	Methods
Keys	PassKey, Fido2Key, UserKey
OTP	Phone, Email
OAuth	Telegram, Google, Discord, GitHub, VK, Apple, Facebook
Service	AppLogin, AuthProxy (inter-service)

Chat - More Than Messaging

Capability	Details
SMS	Twilio, Smsc, Infobip, Nexmo, SmsApi
Email	OTP, password reset, custom emails
Telegram	Bot integration
Files	Metadata storage (files on AuthProxy file service)
Feedback	Reviews with ratings
Tasks	Task management linked to chats

Core Module (You Own and Control)

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

Example:

• Standard modules provide auth, wallet, messaging
• Your core module implements: order management, inventory, custom workflows

4. Two PWA Frontend Architectures

ItBuild uses different technologies for different needs:

AuthProxy PWA (Preact)

Why Preact? Authentication form is the first page users see. Size and speed are CRITICAL.

Aspect	Details
Framework	Preact 10.28 (3KB vs React 40KB)
Repository	/apg.pwa (separate Git repo)
Bundle Target	< 200KB compressed (STRICT!)
Deployment	dist/ → AuthProxy/wwwroot/
Routing	preact-iso
State	Context API, custom hooks

Other Modules PWA (React)

Why React? Not first load, richer functionality needed, larger ecosystem.

Aspect	Details
Framework	React 19
Repositories	/trexwallet.pwa, /chat.pwa, etc.
Bundle Target	< 500KB compressed
Deployment	dist/ → AuthProxy/wwwroot/wallet/
Routing	React Router DOM
State	Zustand
Architecture	Feature-Sliced Design (FSD)
UI Libraries	Tailwind CSS 4, Emotion, @headlessui

5. Admin Pages (Backend, Not Frontend!)

Critical Misconception: Admin pages are NOT frontend work.

Reality: Admin pages are Razor Pages (server-rendered C#) with minimal JavaScript.

Aspect	Technology
Backend	ASP.NET Core Razor Pages (C#)
Database Access	Dapper queries
Business Logic	Server-side page handlers
Frontend (minimal)	jQuery + DataTables + PostCore
Styling	Pure CSS (no frameworks)

Complexity is in backend:

• Data retrieval queries
• Null semantics (null = don't update)
• ApiResponse handling
• Validation

6. Horizontal Scaling Architecture

AuthProxy supports horizontal scaling with session locality (no synchronization overhead):

main.app.com (DNS Round Robin) → IP1, IP2, IP3
         ↓
Frontend probes p1, p2, p3 subdomains in parallel
         ↓
Switches to fastest responding proxy (single IP)
         ↓
Session is LOCAL to this proxy (no sync needed)

Benefits:

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

Audit Logging (login_log table):

• IP address + geolocation
• Device info (user agent)
• Screen resolution
• Device GUID (fingerprint)
• Timezone, browser language

7. Docker Deployment Strategy

Philosophy: Store binaries, not container versions.

Base Image Approach

# Single base image for ALL services
FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine
WORKDIR /app
ENTRYPOINT ["dotnet"]

Binary Storage

/projects/{projectId}/
├── AuthProxy/
│   ├── 1.0.0/  (binaries + wwwroot)
│   ├── 1.0.1/
│   └── 1.2.0/  (latest)
├── TrexWallet/
│   └── 1.0.0/
└── configs/
    ├── authproxy.json
    └── wallet.json

Container Assembly at Runtime

# AuthProxy
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

# TrexWallet (internal)
docker run -d \
  --name project123-wallet \
  --network project123_net \
  -v /projects/123/TrexWallet/1.0.0:/app:ro \
  -v /projects/123/configs/wallet.json:/app/appsettings.json:ro \
  itbuild/dotnet-base:10.0 \
  TrexWallet.dll

Benefits:

• Easy rollback - just mount previous version
• Storage efficient - one base image, many projects
• Fast deployment - no image build needed
• Version flexibility - each module independently versioned

Project Lifecycle

Phase 1: Project Creation

1. Customer registers on ItBuild.app
2. Creates project:
   • Project name
   • Domain (e.g., app.yourcompany.com)
   • Selected modules
3. System assigns:
   • ProjectID (TimeTick)
   • DEV port (e.g., 8001)
   • VM for resources

Database Record: The project registry stores the project id, owner, domain, selected modules, assigned environment, and verification status.

Phase 2: Domain Verification

1. System provides TXT record:

   _itbuild-verify.app.yourcompany.com
   TXT "{ProjectID}:{AppID}"

2. Customer adds DNS record

3. System verifies ownership

4. Status: pending_verification → verified

Phase 3: Provisioning

File Structure: Each project receives isolated folders for module artifacts, runtime configuration, and deployment metadata.

Databases: Selected modules receive their own databases or schemas according to the module template.

Configuration Files:

• Generate authproxy.json
• Generate wallet.json
• Set connection strings
• Generate API keys

Phase 4: License Binding

The system compiles modules with your specified domain embedded into the binary. Modules will only function on that domain (plus platform development sentinels for testing). For Startup / Standalone / Subscription tiers, this step requires DNS-verified domain ownership; for Personal Free, any specified domain is accepted without DNS verification.

Phase 5: Initial Build

1. Modules built for your domain
2. Builds all modules:
   • AuthProxy
   • TrexWallet
   • Chat
   • Customer's Core module
3. Builds PWA frontends:
   • apg.pwa (Preact)
   • trexwallet.pwa (React)
   • chat.pwa (React)
4. Copies binaries to /projects/{projectId}/Module/1.0.0/
5. Records build in database

Phase 6: DEV Deployment

1. Creates Docker network: project{projectId}_net
2. Starts containers:
   • AuthProxy on port (e.g., 8001)
   • Other modules on internal network
3. Configures edge forwarding:
   • Public customer endpoint → project VM customer port
4. Customer can access the project through its assigned endpoint

Phase 7: Development

Customer develops Core module:

• Git repository access
• Standard API patterns
• Automated builds on push
• Auto-deploy to DEV

Phase 8: Production Deployment

Option A: Customer deploys themselves

• Download deployment package
• Run on own infrastructure
• Follow deployment guide

Option B: ItBuild assists

• Consultation
• Initial setup
• Training

Monitoring & Operations

Uptrace (Logs & Telemetry)

All modules integrated with OpenTelemetry:

• Distributed tracing
• Request logs
• Error tracking
• Performance metrics

Grafana (Metrics Visualization)

Dashboards for:

• Container health (CPU, memory, disk)
• Request rates, error rates
• Database performance
• Module communication latency

Zabbix (Infrastructure Monitoring)

• VM health
• SQL Server performance
• Disk space alerts
• Network throughput

Key Technologies

Multi-Database Support

AuthProxy supports multiple database engines for different deployment scenarios:

Database	Use Case	Notes
SQL Server	Production with TrexWallet	Full features, TVP support
SQL Server Express	Development, small projects	Free, 10 GB database limit
SQLite	Standalone mode, edge deployment	Lightweight, no server required
PostgreSQL	Open source alternative	Full ANSI SQL support

All modules use the DbCore abstraction (DbCore, DbCoreSQLite, DbCorePostgres) with ANSI-compatible SQL queries for portability.

TimeTick ID System

Distributed ID generation without coordination:

Every record id is time-sortable and can be generated independently by modules without a database roundtrip.

Benefits:

• No auto-increment (works across distributed systems)
• Sortable by creation time
• Embeds metadata (service, type)
• No database roundtrip

ApiResponse Format

Consistent JSON-RPC-like format across all modules:

{
  "result": { /* success data */ },
  "error": {
    "code": -1,
    "message": "Error description"
  },
  "id": "request_nonce"
}

Module APIs return the same envelope for success and error results so clients can process responses uniformly.

Null Semantics

Critical pattern for updates: omitted or null fields mean "do not update this value". This protects partial updates from clearing existing data.

Database: NO NULL fields allowed (use DEFAULT values)

Platform Benefits Summary

For Customers

✅ Faster Time to Market - Reuse standard modules ✅ Lower Development Cost - Focus on business logic only ✅ Enterprise Security - FIDO2, MFA, audit logs ✅ Scalability - Proven architecture ✅ Full Control - Own your core module source ✅ Flexibility - Deploy on your infrastructure

For ItBuild Team

✅ Shared Maintenance - Fix once, benefit all customers ✅ Economies of Scale - Infrastructure costs spread ✅ Rapid Deployment - Automated provisioning ✅ Quality Control - Standard modules battle-tested ✅ Predictable Operations - Consistent architecture

Recent Platform Updates (May 2026)

Hybrid Payment Ownership

The Payment Gateway moved to a hybrid model:

• TrexWallet keeps the ledger (transact, tariff, address_transact writes).
• Customer Core owns provider-side flow (acquiring widget, P2P matching, custom UX).
• Single switching point POST /payment/v1/payment_order_start applies the tariff and creates address_transact for both built-in and customer flows.
• Customer continuation routes through tokens_networks.flow_path instead of the deleted ICorePaymentProvider HTTP interface.
• pay_wire / initiate_wire_payment removed — bank wire is part of customer continuation.
• payment-gate.pwa decommissioned; the universal /pay and /pay-auth pages now live inside trexwallet.pwa.

CRM Verified Contacts

• New flags user_exid_flags.Verified and ManuallyAdded distinguish OTP-confirmed contacts from operator-added ones.
• /CrmAdmin/ExternalIds shows colour-coded badges and exposes a "Mark verified" action with audit (CrmAuditAction.ExidVerified).
• AuthProxy login flows (OTP, magic link, OAuth with EmailVerifiedByProvider, federation) set Verified automatically.

AuthProxy Inbound Email Bridge

• SMTP listener on port 25 turns inbound mail into chat messages.
• Anonymous chat invites and CRM users share the code@<project-domain> shape.
• DKIM (relaxed/relaxed) + minimal SPF + strict From:-alignment.
• Reply-from-chat back to email handled by EmailNotifyHook in Chat.

Recent Platform Updates (April 2026)

Terminals API & DB Unification

• Single TerminalOut family (WalletTerminalOut for /pay, TerminalInternalOut for S2S, TerminalIn for write).
• tokens_networks got UI columns (display_name, icon_code, instructions, capabilities, countries, tag) and a per-terminal RequirePartnerInfo flag.
• banks column renamed to capabilities with per-type_contract semantics (card networks, P2P banks, SEPA / SWIFT schemes, optional crypto traits).
• paymentMethod: string and tokenNetwork: string removed from DTOs; UI grouping derived from TerminalUiCategory.

Acquiring Scanner

• TrexWallet.Acquiring sidecar service for built-in card acquiring.
• Stripe Checkout (type_network=190) + T-Bank (type_network=191).
• pending_acquiring_txs generic helper for any acquiring scanner / customer Core to reconcile pending state.

Chat Calls Move

• video_calls table dropped; calls live as ordinary chat_mess rows with ChatMessFlags.Call=512 and CallMessageContent JSON.
• Direct (1:1) call runtime fully in-memory (CallService._activeCalls); zero-SQL hot path for SendSignal / HeartbeatCall.

AuthProxy Embedded STUN + Diagnostics

• Embedded STUN responder bound to the same web port (UDP) for NAT traversal without external dependency.
• Authenticated diagnostics endpoint /auth/v1/stun/{report,current} and operator panel /ProxyAdmin/StunMonitor.

CORS App × Route Pair

• CORS for cross-app calls is gated by two flags simultaneously (AppFlag.AppAuthAndCORS on user_app AND RouteFlags.AppAuthAndCORS on route_map).

Federation v2 — Manual Provider Picker

• New endpoints: GET /auth/v1/federated/providers, GET /auth/v1/federated/start.
• Login form Form0 renders the partner provider catalogue from this list — adding a partner no longer requires a PWA rebuild.
• returnUrl is rebuilt server-side to prevent open redirects.

Recent Platform Updates (March 2026)

Pre-Release Audit & Safe Fixes

Comprehensive dev-to-master audit across all modules (AuthProxy, TrexWallet, Chat, CRM, Scanners) — 6 batches of safe fixes applied:

• Null semantics enforcement — 21 non-nullable value type properties made nullable across 6 entity classes to prevent silent data corruption.
• Session security — exact ApgSession limit boundaries + expired-session cleanup on access.
• Runtime cache consistency — immediate user_app cache refresh after create/update/delete.
• Chat pin/unpin fix — no longer runs async side effects inside React state updater.
• File access model — raw fileId now requires authenticated owner/member access.

Observability (Uptrace v2)

• Uptrace v2 deployed with Docker Compose for centralized tracing and logging.
• Per-project Uptrace setup via setup-uptrace-project.sh.
• UptraceDsn injected into all module and scanner configs during deploy.

TrexWallet Monitoring

• TrexMonitor singleton — unified source of runtime + DB metrics (5s cache).
• GET /private/v1/monitoring_stats — process, config, caches, db (scanners, KPI).
• Public get_info returns clean ModuleInfo (BlockchainInfo removed from Swagger).

CI/CD Automation

• Automated pipelines for customer PWA and Core builds.
• provision.sh + setup-repos.sh — full project setup from scratch (all 12 containers).

Documentation Sync

• Federation v2 docs synced across all customer-facing and module-delivery documents.
• TrexWallet BankTransfer + FederationCredit transaction type numbering aligned.

Recent Platform Updates (February 2026)

Payment Gateway (initial release; see hybrid refactor in May 2026 above)

• Universal payment page with 5 payment methods released.
• Note: the initial release used ICorePaymentProvider for custom Core flows; that interface was removed in v1.4.0 and replaced with flow_path + tx_list_push UpdateOnly.

Federation v2

Federation v2 connects partner projects through existing platform primitives — see April 2026 update above for the manual provider picker UX.

WebRTC Calls (initial release; see April 2026 storage move)

1:1 audio/video calls launched in Chat module. Initial release used a dedicated video_calls table; that table was dropped in 2026-04-29 — calls now live in chat_mess.

CRM Standard Features

• Notes, Tags, Audit Log, Addresses, Custom Fields.
• 6 new admin pages, 6 error codes.
• 75 unit tests.

MCP Enhancements

43 built-in AI tools across all modules for Claude Code integration.

Data Model Boundaries

API responses now use proper DTOs instead of raw DB entities (TransactPvt, WalletInfoPvt, CurrencyPvt, …) and SSE unified to BroadcastEvent format.

Next Steps

• Create Your Project - Start building
• Real-time Events & MCP - SSE, Webhooks, AI integration
• License System - How licensing works
• Core Module Development - Build your business logic