# 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
```bash
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
```bash
cd frontend
bun install
bun run dev
bun run build
bun run preview
```

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

### Docker
```bash
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
```sql
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
```sql
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
```sql
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
```json
{
  "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
```json
{
  "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 |