UBA Backend Module Overview

This document organizes the GoWind UBA backend's code structure, the service layer inventory of the three services, the shared packages (pkg), and a directory quick reference, helping secondary developers locate code quickly.

1. Backend Directory Structure

backend/
├── api/                            # Protobuf API definitions and generated code
│   ├── protos/                     # .proto source files (layered by domain)
│   │   ├── admin/service/v1/       # Admin console HTTP gateway protos (the sole input for the TS client)
│   │   ├── uba/service/v1/         # UBA domain messages + gRPC service contracts
│   │   └── <other domains>/             # authentication / dict / permission / identity ...
│   └── gen/go/                     # Go code generated by buf
├── app/                            # Service applications
│   ├── admin/service/              # Admin service (admin console BFF, thin forwarding)
│   ├── collector/service/          # Collector service (event tracking ingestion BFF)
│   └── core/service/               # Core service (core business logic)
│       └── internal/
│           ├── data/               # Data layer (ent repo / OLAP repo / client)
│           │   ├── ent/schema/     # ent entity definitions (edit here → make ent)
│           │   ├── doris/          # Doris repo (with schema/ fact table definitions)
│           │   └── clickhouse/     # ClickHouse repo (with schema/ fact table definitions)
│           ├── service/            # Business service implementations
│           └── server/             # grpc / rest server registration
├── pkg/                            # Shared packages
├── sql/                            # Database scripts (clickhouse / doris / postgresql)
├── scripts/                        # Deployment scripts (deploy / docker / env)
└── Makefile                        # Code generation / build commands

Each service directory follows the standard kratos layout: cmd/server/ (entry point) + configs/ (YAML configuration) + internal/{conf,data,server,service}/.

2. Core Service (Core Business)

Directory: backend/app/core/service/internal/service/, carrying almost all business logic. Grouped by responsibility:

Data Collection & Events

Service	Corresponding proto	Responsibility
`BehaviorEventService`	`behavior_event.proto`	Behavior event ingestion (`Create`/`BatchCreate`), `List`/`Get`
`SessionService`	`session.proto`	Session fact table CRUD
`EventPathService`	`event_path.proto`	User path fact table CRUD
`EventSchemaService`	`event_schema.proto`	Event schema management (event name/property validation and registration)
`ObjectService`	`object.proto`	Behavior object (object_type/object_id) management
`ApplicationService`	`application.proto`	UBA app management (generates appId/appKey/appSecret)

Analytics Modeling

Service	Corresponding proto	Responsibility
`AnalyticsService`	`analytics.proto`	25 analysis models: covering seven major scenario groups — basic aggregations, conversion paths, in-depth user insights, lifecycle, revenue value, session anomalies, and game-specific (see Backend API · Analytics Aggregation Service). Branches to the Doris / ClickHouse repo based on the `UseClickHouse` compile-time constant

Risk & Tags

Service	Corresponding proto	Responsibility
`RiskEventService`	`risk_event.proto`	Storage/retrieval of risk event results (`Create`/`BatchCreate`/`List`)
`RiskRuleService`	`risk_rule.proto`	Risk rule definition CRUD
`TagDefinitionService`	`tag_definition.proto`	Tag definition CRUD
`UserTagService`	`user_tag.proto`	User tag associations
`IdMappingService`	`id_mapping.proto`	Cross-platform ID mapping (identity graph)
`UserBehaviorProfileService`	`user_behavior_profile.proto`	User behavior profile fact table CRUD
`WebhookService`	`webhook.proto`	Webhook configuration (risk alert push)

Organization & Permissions

Service	Responsibility
`TenantService`	Multi-tenant management
`UserService` / `UserCredentialService`	Full user lifecycle, login credentials
`RoleService` / `PermissionService` / `PermissionGroupService`	Roles, permissions, permission groups
`OrgUnitService` / `PositionService`	Organization structure, positions
`MenuService`	Menu nodes
`DictTypeService` / `DictEntryService`	Data dictionaries
`LanguageService`	Multi-language
`LoginPolicyService`	Login policy
`ApiService`	API metadata registration

System Operations

Service	Responsibility
`AuthenticationService`	Login authentication, token issuance
`FileService` / `FileTransferService`	File storage (MinIO), file transfer
`InternalMessageService` (+ Category / Recipient)	In-app messages
`TaskService`	Asynchronous tasks (Asynq)
Audit logs (5 types)	`LoginAuditLogService` / `OperationAuditLogService` / `ApiAuditLogService` / `PermissionAuditLogService` / `DataAccessAuditLogService` / `PolicyEvaluationLogService`

For the complete proto contracts, see Backend API Contract.

3. Admin Service (Admin Console BFF)

Directory: backend/app/admin/service/internal/service/. All implementations are thin forwarding: they implement adminV1.XxxHTTPServer and call the corresponding Core gRPC client (ubaV1.XxxClient) inside method bodies, with no business logic.

Admin services correspond one-to-one with Core services: analytics_service.go, application_service.go, behavior_event_service.go, risk_event_service.go, user_service.go, role_service.go, and about 40+ forwarding implementations in total.

For the complete steps to add a new external HTTP capability, see the Adding an External Service tutorial.

4. Collector Service (Ingestion BFF)

Directory: backend/app/collector/service/. Single responsibility: receives POST /uba/v1/report, performs application authentication and field validation/completion, then publishes to Kafka. It has no business service layer of its own; the logic is concentrated in the transport layer and pkg/topic (Kafka topic management).

5. Shared Packages (pkg)

Directory: backend/pkg/, shared by the three services:

Package	Responsibility
`authorizer`	Authentication engine wrapper (Casbin / OPA)
`constants`	Constant definitions
`crypto`	Encryption utilities (AES-GCM etc.)
`jwt`	JWT utilities (issue/verify)
`metadata`	Request metadata management (tenantId injection etc.)
`middleware`	Middleware (auth/logging/Ent/metadata)
`oss`	Object storage (MinIO / S3 compatible)
`serviceid`	Service identity
`task`	Asynchronous tasks (Asynq wrapper)
`topic`	Kafka topic management (`uba_events_raw` / `uba_risk_events`)
`utils`	General utilities
`entgo`	Ent extensions (go-crud generic Repository wrapper, mixins, etc.)

6. Data Layer Essentials

PostgreSQL (Ent)

Entity definitions live in app/core/service/internal/data/ent/schema/, with table names declared via entsql.Annotation{Table: ...}.
There is no hand-written schema.sql — table structures are generated by make ent; sql/postgresql/ contains only dictionary seed data (default-data.sql) and demo data.
Business table prefixes: sys_ (system/RBAC/i18n/dictionaries), uba_ (UBA business), and others such as files, internal_messages.

OLAP (Doris / ClickHouse)

Fact table schemas are mirrored in app/core/service/internal/data/{clickhouse,doris}/schema/, consistent with the sql/{clickhouse,doris}/ scripts.
Main fact tables: events_fact, sessions_fact, risk_events, path_features; dimension tables: users_dim, objects_dim, id_mapping, user_tags.
Aggregation queries use native SQL (not Ent); dimension fields go through a whitelist, metrics go through a switch, and numeric values are strongly cast before concatenation to prevent injection.