Getting Started
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This guide helps you set up and run the BI Analysis Platform locally, covering both frontend and backend components. It explains prerequisites, environment setup, service configuration, quick start workflows, and troubleshooting. The platform integrates modern technologies including Next.js for the frontend, Kratos microservices for the backend, StarRocks for analytics, Kafka for streaming, and optional AI components for conversational analytics.
Project Structure
The repository is a monorepo containing multiple services and shared libraries:
- Frontend applications: ui-web (tenant console), ui-web-admin (operations), ui-web-tech, ui-web-top, ui-crx
- Backend services: bi-analysis (core analysis), bi-basic, bi-plan-taoxi, bi-api-leke, bi-api-jushuitan, bi-chat, bi-notify, bi-sys, bi-tenant, bi-cron, bi-server
- Shared libraries: bi-common (components), bi-proto (IDL), bi-template (boilerplate)
- Infrastructure: APISIX gateway, Nacos configuration center, Docker/Kubernetes artifacts
Diagram sources
Section sources
Core Components
- Frontend stack: Next.js 16 with TypeScript, Tailwind CSS, ECharts, Zustand, and multiple UI apps.
- Backend stack: Golang with Kratos framework, gRPC/Protobuf, Kafka, StarRocks, APISIX gateway.
- AI component: Python-based agent server with FastAPI and Qwen-Max for conversational analytics.
- Shared infrastructure: bi-common provides Nacos, logging, database, Redis, Kafka, and utilities.
Key entry points:
- Frontend: ui-web development server runs on port 3000.
- Backend: bi-analysis binary supports environment flags (dev/test/prod).
- AI: bi-chat exposes a FastAPI service configured via .env.example.
Section sources
Architecture Overview
The platform follows a modular microservices architecture with a shared component library and standardized configuration via Nacos. The frontend communicates with backend services through HTTP/gRPC, while real-time data is handled via Kafka. StarRocks serves analytical queries, and APISIX routes traffic.
Diagram sources
Detailed Component Analysis
Local Environment Setup
- Prerequisites:
- Go 1.25+ for backend services
- Node.js and pnpm/yarn/npm for frontend
- Docker for containerized builds and optional runtime
- Optional: Kafka, StarRocks, Nacos, Milvus, PostgreSQL, Neo4j for full local stack
- Install dependencies:
- Backend: run dependency management in each service directory as needed.
- Frontend: install dependencies in ui-web and other UI packages.
Quick start references:
- Frontend dev server: [ui-web README]
- Backend dev server: [bi-analysis README]
Section sources
Frontend Services
- ui-web (tenant console): Next.js app with TypeScript and Tailwind CSS.
- Run development server using npm/yarn/pnpm.
- Build scripts and environment variables are defined in package.json.
- Other UI apps: ui-web-admin, ui-web-tech, ui-web-top, ui-crx follow similar patterns.
Diagram sources
Section sources
Backend Services
- bi-analysis (core analysis service):
- Uses Kratos framework and integrates bi-common.
- Supports environment flags: dev/test/prod.
- Configuration via Nacos and YAML files.
- Build with Makefile targets and Dockerfile.
Diagram sources
Section sources
- [bi-analysis/README.md]
- [bi-analysis/configs/application-local.yaml]
- [bi-analysis/Dockerfile]
- [bi-common/README.md]
AI Component (bi-chat)
- Purpose: Conversational analytics powered by Qwen-Max via AgentScope/FastAPI.
- Configuration keys include LLM API key, model name, StarRocks connection, PostgreSQL, Milvus, Redis, and Neo4j.
- Use .env.example as a template for local environment variables.
Diagram sources
Section sources
Shared Infrastructure (bi-common)
- Provides Nacos integration, unified response format, logging, database (GORM), Redis, Kafka, and utilities.
- Environment variable naming convention and configuration precedence are documented.
Diagram sources
Section sources
Dependency Analysis
- Go modules:
- bi-common declares Kratos, Nacos SDK, GORM, Redis, Kafka, and related dependencies.
- bi-analysis depends on bi-common and bi-proto, with Kratos, gRPC, Wire, and gateway.
- Frontend dependencies:
- ui-web uses Next.js 16, React 19, ECharts 6, Zustand, Tailwind, and related UI libraries.
Diagram sources
Section sources
Performance Considerations
- Use production-like configurations for performance testing.
- Enable gzip/HTTP/2 in APISIX for reduced latency.
- Optimize StarRocks queries and partitioning for analytical workloads.
- Tune Kafka consumer lag and batch sizes for real-time pipelines.
- Monitor backend metrics via Kratos observability and Prometheus.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common setup issues and resolutions:
- Frontend fails to start:
- Ensure Node.js and package manager are installed and dependencies are fetched.
- Verify environment variables for the UI app if applicable.
- Backend fails to connect to Nacos:
- Confirm Nacos server address/port and credentials match the local configuration.
- Check data IDs in Nacos: bi-common.yaml and bi-analysis.yaml.
- Backend cannot reach databases or caches:
- Validate host, port, username/password for StarRocks, Redis, PostgreSQL, Milvus, Neo4j.
- Ensure containers/services are running and reachable from the host.
- AI component errors:
- Set DASHSCOPE_API_KEY and MODEL_CONFIG_NAME in .env.
- Verify network connectivity to LLM provider and local ports for infrastructure services.
Environment variable examples:
- Nacos: server address, port, namespace, group, timeouts, and credentials.
- Database connections: host, port, user, password, database name.
- Caches: Redis host/port/password/db.
- Vector/graph stores: Milvus and Neo4j URIs and credentials.
- PostgreSQL: connection URL.
Section sources
- [bi-analysis/configs/application-local.yaml]
- [bi-common/registry/nacos/nacos-default.yaml]
- [bi-chat/.env.example]
Conclusion
You now have the essentials to install, configure, and run the BI Analysis Platform locally. Start with the frontend and backend quick starts, then integrate shared infrastructure (Nacos, StarRocks, Kafka) and optional AI services. Use the troubleshooting section to resolve common setup issues.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Quick Start Checklist
- Frontend
- Install dependencies in ui-web.
- Run development server and open http://localhost:3000.
- Backend
- Initialize dependencies and build bi-analysis.
- Start bi-analysis with -env dev/test/prod.
- AI
- Copy .env.example to .env and set required keys.
- Start bi-chat FastAPI service.
Section sources