Multi-Regional Restructuring¶
SectorWars 2102 runs as a Central Nexus hub (5000 sectors, 10 districts) plus per-region 500-sector territories that players own via PayPal subscription.
1. Architecture¶
Central Nexus¶
5000 sectors organized into 10 specialized districts:
| District | Role |
|---|---|
| Commerce Central | Premium trading facilities |
| Diplomatic Quarter | Inter-regional negotiations |
| Industrial Zone | Manufacturing complexes |
| Residential District | Citizen services |
| Transit Hub | Warp gate infrastructure |
| High Security Zone | Restricted access |
| Cultural Center | Events / festivals |
| Research Campus | Tech development |
| Free Trade Zone | Unrestricted commerce |
| Gateway Plaza | Welcome / orientation |
Galactic governance sits on a council, with the Nexus acting as the universal trade hub for all regional territories.
Regional territories¶
- 500 sectors each, player-owned.
- Subscription tiers via PayPal: $25/mo regional ownership, $5/mo galactic citizenship.
- Configurable governance: Democracy, Autocracy, Council Republic.
- Configurable economy: tax rate (5-25%), starting credits (100-10,000), trade bonuses (1.0-3.0x), economic specialization.
- Cultural identity (language pack, aesthetic theme, traditions, motto).
Container topology¶
Per docker-compose.multi-regional.yml:
- Central Nexus services: nexus-gateway (Nginx), nexus-gameserver, nexus-database (Postgres), nexus-redis.
- Regional services (template): region-template, region-database, region-cache — provisioned dynamically per subscription.
- Management: region-manager (orchestrator on port 8081), monitoring stack (Prometheus, Grafana), centralized logging.
Networks: nexus_network (172.20.0.0/16), regional_network (172.21.0.0/16), per-region (172.22.x.0/24).
Resource targets per region: 2 vCPU / 4 GB / 20 GB / 100 players default; auto-scale up to 8 vCPU / 16 GB / 100 GB / 1000 players. Auto-scale up at >80% CPU or >85% memory; down at <20% CPU and <30% memory sustained.
2. Code surface¶
Database schema — regions, regional_memberships, regional_policies, regional_elections, regional_votes, regional_treaties, inter_regional_travels, plus an enhanced sectors table with region_id, district, security_level, development_level, traffic_level.
Models — Region, RegionalMembership, InterRegionalTravel in gameserver.
Services — regional_auth_service.py, regional_governance_service.py, nexus_generation_service.py.
API:
- /api/v1/regions/* — owned region info, stats, economy/governance config, policy proposals, elections, treaties, culture, members.
- /api/v1/nexus/* — status, stats, districts, generate/regenerate nexus, regenerate district.
Admin UI — pages/CentralNexusManager.tsx and pages/RegionalGovernorDashboard.tsx (7-tab interface for Overview, Governance, Economy, Policies, Elections, Diplomacy, Culture).
Player client — regional-selection UI, cross-regional travel view, and player-facing governance panel.
3. Subscription / provisioning flow¶
Player → PayPal: subscribe ($25/mo)
PayPal → Platform: webhook
Platform → region-manager: provision request
region-manager → Docker: create containers from template
Docker → region-manager: containers ready
region-manager → Central Nexus: register region
Provisioning steps: 1. Validate subscription status. 2. Create isolated database. 3. Generate region configuration. 4. Deploy container stack from template. 5. Register with Central Nexus. 6. Configure inter-regional routing.
Termination: 1. 30-day evacuation notice to players. 2. Backup + export. 3. Container cleanup. 4. DB removal. 5. Network cleanup.
4. Performance targets¶
| Metric | Target |
|---|---|
| Central Nexus generation | 15-20 min for 5000 sectors |
| Regional stats query | <2 s |
| Policy CRUD | <1 s |
| Dashboard load | <3 s |
| Complex regional aggregations | <500 ms |
| Concurrent regions | 100+ |
| Players per region | 500+ concurrent |
| Nexus capacity | 10,000+ concurrent |
API SLO: p95 <1 s response. Pool utilization <80%, CPU <70%, memory <80%.
5. Operations¶
Setup¶
chmod +x scripts/setup-multi-regional.sh
./scripts/setup-multi-regional.sh
nano .env.multi-regional # PayPal credentials
docker-compose -f docker-compose.multi-regional.yml up -d
CLI¶
./scripts/region-cli.py list
./scripts/region-cli.py show <region>
./scripts/region-cli.py scale <region> --cpu 4 --memory 8 --disk 40
./scripts/region-cli.py config sample-region.yml
Health / metrics¶
curl http://localhost/api/v1/status/health
curl http://localhost/api/v1/region-manager/metrics
docker-compose logs -f central-nexus-server
docker-compose logs -f region-<name>-server
Grafana dashboards at http://localhost:3002.
Backup¶
- Central Nexus: daily full + hourly incremental.
- Regional: daily per region.
- Configuration: git.
- Retention: 30 days online, 1 year archived.
6. Cost model¶
- Base platform: ~$200/mo (64 vCPU server).
- Per region: $5-15/mo cost vs $25/mo + $5/mo citizen revenue.
- Break-even: ~15 active regions.
7. Key files¶
Backend
- services/gameserver/src/models/region.py (Region, RegionalMembership, InterRegionalTravel)
- services/gameserver/src/services/regional_auth_service.py
- services/gameserver/src/services/regional_governance_service.py
- services/gameserver/src/services/nexus_generation_service.py
- services/gameserver/src/api/routes/nexus.py
- services/gameserver/src/api/routes/regional_governance.py
Admin UI
- services/admin-ui/src/components/pages/CentralNexusManager.tsx
- services/admin-ui/src/components/pages/RegionalGovernorDashboard.tsx
Infra
- docker-compose.multi-regional.yml
- scripts/setup-multi-regional.sh
- scripts/region-cli.py