planet/project_context.md

project_context.md

AI 需要知道的静态事实。用于理解项目，非约束。

---

Project Overview

智能星球计划 (Intelligent Planet Plan) - A situational awareness system for data-centric competition.

Core Vision

构建人类智能空间的"实时全景图" - 在智能时代，同时监测"现实层宇宙"和"认知层宇宙"。

Four Core Elements

Layer	Element	Description
L1	新兴技术支撑	AI算力、模型生态、云基础设施
L2	关键基础设施	卫星、海底光缆、IXP、路由
L3	组织制度资源	规则制定权、顶层设计
L4	文化内容供给	新闻、社交视频、舆论情绪

---

Technology Stack

Current implementation truth lives in README.md, CODEMAP.md, and docs/technical/{zh,en}/. This file is background context; when it conflicts with current code or harness checks, prefer the current implementation docs.

Backend

• Framework: Python FastAPI 0.109+
• ORM: SQLAlchemy 2.0+
• Database Migration: Alembic / SQLAlchemy migrations
• Task Runtime: APScheduler, backend background tasks, and database job state
• Runtime Coordination: Redis 7.0+ cache/streams
• Package Manager / Runner: uv

Frontend

• Framework: React 18
• UI Layer: Tactile UI, Radix primitives, lucide-react
• HTTP Client: Axios
• State Management: Zustand and local React state
• Real-time: Socket.io-client
• Charts: ECharts
• Package Manager / Runner: Bun 1
• 3D Earth: Three.js Web Earth

Visualization Direction

• Current: Browser Web Earth with Three.js assets under frontend/public/earth/
• Future / optional: UE5, Cesium for Unreal, and Niagara remain physical big-screen exploration directions, not required local development dependencies.

Database

• Relational: PostgreSQL 15+ (users, config)
• Cache / Streams: Redis 7+ (sessions, cache, runtime events)
• Future / optional: TimescaleDB, MinIO, Kafka, and Celery are evolution boundaries only; do not assume they exist in the active local stack.

Deployment

• Container: Docker 24+
• Orchestration: Docker Compose
• Packaging: Helm chart under deploy/helm/planet/

---

Project Structure

├── backend/                   # FastAPI Backend
│   ├── app/
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── auth.py
│   │   │   │   ├── users.py
│   │   │   │   ├── datasources.py
│   │   │   │   ├── docs.py
│   │   │   │   └── websocket.py
│   │   │   └── endpoints/
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   ├── security.py
│   │   │   └── websocket_manager.py
│   │   ├── models/
│   │   │   ├── user.py
│   │   │   ├── datasource.py
│   │   │   └── task.py
│   │   ├── schemas/
│   │   │   ├── user.py
│   │   │   └── datasource.py
│   │   ├── services/
│   │   │   ├── collectors/
│   │   │   │   ├── base.py
│   │   │   │   ├── top500.py
│   │   │   │   ├── epoch_ai.py
│   │   │   │   └── huggingface.py
│   │   │   └── analysis.py
│   │   ├── tasks/
│   │   ├── services/
│   │   │   ├── collectors/
│   │   │   └── docs_gatekeeper.py
│   │   └── db/
│   │       └── database.py
│   ├── tests/
│   │   ├── test_api.py
│   │   └── test_realtime_sources.py
│   └── alembic/
│
├── frontend/                  # React Admin, Docs UI, and Web Earth shell
│   ├── src/
│   │   ├── admin/            # Console routes, pages, Tactile/Radix wrappers
│   │   ├── components/       # Reusable UI and Web Earth components
│   │   ├── pages/            # Public route pages
│   │   │   ├── Login/
│   │   │   ├── Register/
│   │   │   ├── Docs/
│   │   │   └── Earth/
│   │   ├── stores/           # Zustand stores
│   │   ├── hooks/
│   │   └── App.tsx
│   ├── package.json
│   └── public/earth/          # Web Earth static assets
│
├── aiprovider/                # Model provider/protocol adapter service
├── motion_agent/              # Motion capture protocol service
├── deploy/helm/planet/        # Helm chart
├── docs/                      # Documentation
├── scripts/                   # Utility and harness scripts
├── docker-compose.yml
├── pyproject.toml
├── uv.lock
├── .env.example
├── rules.md
├── project_context.md
├── AGENTS.md
└── README.md

---

Role-Based Access Control

Role	Permissions	Description
super_admin	Full access	System init, 不可删除
admin	All except user management	Daily operations
operator	View + manual operations	Manual refresh, alert confirm
viewer	Read-only	View dashboard only

Default Users (MVP)

• admin / admin123 (super_admin)
• operator / operator123 (operator)
• viewer / viewer123 (viewer)

---

Data Sources

Priority	Source	Frequency	Module	Description
P0	TOP500	4 hours	L1	Supercomputer rankings
P0	Epoch AI	1 hour	L1	GPU cluster data
P0	Hugging Face	2 hours	L1	Model ecosystem
P0	GitHub	4 hours	L1	Code contributions
P0	TeleGeography	Daily	L2	Submarine cables, cloud infra
P0	PeeringDB	2 hours	L2	IXP data
P1	OECD.AI	6 hours	L1	Policy/investment
P1	Cloudflare Radar	1 hour	L2	Traffic/blocking
P1	CAIDA BGPStream	15 minutes	L2	Route monitoring

---

3D Display Specifications

• Display Type: Polarized 3D (glasses-style)
• Screen Size: 2m × 3m
• Resolution: 4K (3840×2160)
• Refresh Rate: 120Hz
• Engine: Unreal Engine 5.3+
• Plugin: Cesium for Unreal

Communication

• WebSocket for real-time data
• 30-second heartbeat
• Data frame updates every 5 minutes (configurable)

---

Build Commands Reference

Backend

uv sync --group dev
cd backend
uv run --project .. python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
docker compose up -d backend
ruff check . && black --check .
pytest -v && pytest tests/api/test_auth.py::test_login -v

Frontend

cd frontend
bun install
bun run dev
bun run build
bun run preview

前端统一使用 Bun，不使用 npm、pnpm、yarn。

Docker

docker-compose up -d
docker-compose logs -f backend
docker-compose up -d --build
docker-compose down

---

API Documentation

After starting the backend, access:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

Common Tasks Workflows

Adding a New Data Collector

1. Create collector class in backend/app/services/collectors/
2. Inherit from BaseCollector
3. Implement fetch() and transform() methods
4. Register in collector_registry.py
5. Add configuration in database
6. Write unit tests

Adding a New API Endpoint

1. Create schema in backend/app/schemas/
2. Create endpoint in backend/app/api/v1/
3. Add to router in backend/app/api/main.py
4. Write integration tests
5. Update API documentation

Fixing a Bug

1. Write failing test first
2. Fix the code to pass test
3. Verify no regressions
4. Document in commit message

---

Database Schema

Users Table

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(20) NOT NULL,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

Permissions Table

CREATE TABLE permissions (
    id SERIAL PRIMARY KEY,
    resource VARCHAR(50) NOT NULL,
    action VARCHAR(20) NOT NULL,
    role VARCHAR(20) NOT NULL
);

Audit Logs Table

CREATE TABLE audit_logs (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    action VARCHAR(100),
    resource VARCHAR(50),
    detail JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

---

Data Models

GPU Cluster

{
  "id": "epoch-gpu-001",
  "name": "Frontier",
  "location": {
    "country": "US",
    "city": "Oak Ridge, TN",
    "lat": 35.9327,
    "lng": -84.3107
  },
  "organization": "Oak Ridge National Laboratory",
  "specs": {
    "gpu_count": 37888,
    "gpu_type": "AMD MI250X",
    "total_flops": 1.54e9,
    "rank": 1
  },
  "last_updated": "2024-01-15T00:00:00Z"
}

Submarine Cable

{
  "id": "cable-001",
  "name": "FASTER",
  "length": 11600,
  "owners": ["Google", "中国移动", "NEC"],
  "points": [
    {"lat": 37.7749, "lng": -122.4194, "city": "San Francisco"},
    {"lat": 35.6762, "lng": 139.6503, "city": "Tokyo"}
  ],
  "capacity": "60 Tbps",
  "status": "active"
}

---

MVP Timeline

Phase	Duration	Deliverables
Phase 1	Week 1-2	Project scaffolding, auth, base framework
Phase 2	Week 3-4	Data collectors (TOP500, Epoch AI, Hugging Face)
Phase 3	Week 5	WebSocket real-time service
Phase 4	Week 6	Admin dashboard
Phase 5	Week 7-8	UE5 3D display integration
Phase 6	Week 9	Testing, deployment, documentation

---

Risk Mitigation

Risk	Likelihood	Impact	Mitigation
Data source API changes	Medium	High	Abstract collector layer, graceful degradation
WebSocket performance	Medium	Medium	Rate limiting, heartbeat optimization
UE5 development overrun	Medium	Medium	Phased delivery (2D → 3D)
Data compliance	Low	High	Legal review
3D compatibility	Low	Medium	Early hardware testing