docs: Add islands-planets agent context file
Documents Islands (personal spaces) and Planets (group spaces) architecture, API endpoints, data models, and TODO roadmap. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Your Name
parent
8e11dc732f
commit
ac99f0f1e4
|
|
@ -0,0 +1,230 @@
|
||||||
|
# Islands & Planets - SocioWire Agent Context
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
SocioWire has two types of virtual spaces:
|
||||||
|
- **Islands** = Personal user spaces (like a profile page but immersive)
|
||||||
|
- **Planets** = Group spaces (like Discord servers/communities)
|
||||||
|
|
||||||
|
Both render as 3D environments that replace the main map view when selected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current State (Jan 2025)
|
||||||
|
|
||||||
|
### Backend (DEPLOYED)
|
||||||
|
- `sociowire/island-service:planets-v1` - Running on swarm
|
||||||
|
- `sociowire/core-api:planets-v1` - Running on swarm
|
||||||
|
|
||||||
|
**Island Service** (`/home/swire/sociowire-code/users-service/island-service/`)
|
||||||
|
- `db.go` - Database connection (YugabyteDB)
|
||||||
|
- `handlers.go` - Island CRUD handlers
|
||||||
|
- `planets.go` - Planet model + CRUD functions
|
||||||
|
- `planet_handlers.go` - Planet HTTP handlers
|
||||||
|
- `main.go` - Server setup
|
||||||
|
|
||||||
|
**Core API Proxies** (`/home/swire/sociowire-code/backend-service/core-api/`)
|
||||||
|
- `island_proxy.go` - Proxies island requests to island-service
|
||||||
|
- `planet_proxy.go` - Proxies planet requests to island-service
|
||||||
|
|
||||||
|
### Frontend (PARTIAL)
|
||||||
|
- `src/api/client.js` - API functions for islands and planets
|
||||||
|
- `src/components/Island/IslandUniverse.jsx` - Universe view (modal) with tabs
|
||||||
|
- `src/components/Island/IslandViewer.jsx` - Individual island viewer
|
||||||
|
- `src/styles/universe.css` - Universe styling with tabs
|
||||||
|
- `src/styles/island.css` - Island viewer styling
|
||||||
|
- Translations in `src/locales/en|fr|es/translation.json`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Models
|
||||||
|
|
||||||
|
### Island (Personal Space)
|
||||||
|
```go
|
||||||
|
type Island struct {
|
||||||
|
ID string // "island-123"
|
||||||
|
UserID int64 // Owner user ID
|
||||||
|
Username string // @username
|
||||||
|
DisplayName string
|
||||||
|
Bio string
|
||||||
|
Seed int64 // For procedural generation
|
||||||
|
VirtualX float64 // Position in universe
|
||||||
|
VirtualY float64
|
||||||
|
VirtualZ float64
|
||||||
|
TerrainType string // tropical, desert, arctic, volcanic, meadow
|
||||||
|
ColorPalette string // vibrant, sunset, pastel, etc.
|
||||||
|
AvatarURL string
|
||||||
|
BannerURL string
|
||||||
|
ContentCount int // Number of posts
|
||||||
|
CreatedAt string
|
||||||
|
UpdatedAt string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Planet (Group Space)
|
||||||
|
```go
|
||||||
|
type Planet struct {
|
||||||
|
ID string // "planet-1"
|
||||||
|
GroupID int64 // Unique group ID
|
||||||
|
Name string // Planet name
|
||||||
|
Description string
|
||||||
|
Seed int64
|
||||||
|
VirtualX float64
|
||||||
|
VirtualY float64
|
||||||
|
VirtualZ float64
|
||||||
|
TerrainType string // tropical, desert, meadow, volcanic, arctic, ocean, crystal
|
||||||
|
ColorPalette string // vibrant, sunset, pastel, monochrome, cosmic, neon
|
||||||
|
Size string // small, medium, large, giant
|
||||||
|
BannerURL string
|
||||||
|
MemberCount int
|
||||||
|
ContentCount int
|
||||||
|
Visibility string // public, private, invite-only
|
||||||
|
OwnerID int64
|
||||||
|
CreatedAt string
|
||||||
|
UpdatedAt string
|
||||||
|
}
|
||||||
|
|
||||||
|
type PlanetMember struct {
|
||||||
|
PlanetID string
|
||||||
|
UserID int64
|
||||||
|
Username string
|
||||||
|
Role string // owner, admin, moderator, member
|
||||||
|
JoinedAt string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
### Islands
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/islands/nearby` | List islands |
|
||||||
|
| GET | `/api/islands/by-username/{username}` | Get island by username |
|
||||||
|
| GET | `/api/islands/{id}` | Get island by ID |
|
||||||
|
| PUT | `/api/islands/avatar` | Sync avatar URL |
|
||||||
|
| PUT | `/api/islands/{id}` | Update island |
|
||||||
|
|
||||||
|
### Planets
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/planets/nearby` | List public planets |
|
||||||
|
| GET | `/api/planets/{id}` | Get planet by ID |
|
||||||
|
| POST | `/api/planets` | Create planet |
|
||||||
|
| PUT | `/api/planets/{id}` | Update planet |
|
||||||
|
| POST | `/api/planets/{id}/join` | Join planet |
|
||||||
|
| POST | `/api/planets/{id}/leave` | Leave planet |
|
||||||
|
| GET | `/api/planets/{id}/members` | Get members |
|
||||||
|
| GET | `/api/user/planets` | Get user's planets |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Frontend API Client
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Islands
|
||||||
|
fetchIslands({ limit }) -> Island[]
|
||||||
|
fetchIslandByUsername(username) -> Island
|
||||||
|
fetchIslandByID(id) -> Island
|
||||||
|
updateIsland(id, updates) -> Island
|
||||||
|
|
||||||
|
// Planets
|
||||||
|
fetchPlanets({ limit }) -> Planet[]
|
||||||
|
fetchPlanet(id) -> Planet
|
||||||
|
createPlanet({ name, visibility }) -> Planet
|
||||||
|
updatePlanet(id, updates) -> Planet
|
||||||
|
joinPlanet(id) -> { ok: true }
|
||||||
|
leavePlanet(id) -> { ok: true }
|
||||||
|
fetchPlanetMembers(id, { limit }) -> PlanetMember[]
|
||||||
|
fetchUserPlanets() -> Planet[]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI Components
|
||||||
|
|
||||||
|
### IslandUniverse (Modal)
|
||||||
|
- Opens from TopBar "Islands" button or SEO section
|
||||||
|
- Shows 3D space map with all islands and planets
|
||||||
|
- **Tabs**: All | Islands | Planets (to filter view)
|
||||||
|
- Click island/planet to open viewer
|
||||||
|
- MapLibre GL for 3D rendering
|
||||||
|
|
||||||
|
### IslandViewer (Full Page Replacement)
|
||||||
|
- Replaces main map when viewing an island
|
||||||
|
- Shows island terrain with posts, apps, documents
|
||||||
|
- Profile editing for own island
|
||||||
|
- Tabs: Profile | Posts | Settings
|
||||||
|
|
||||||
|
### PlanetViewer (TODO)
|
||||||
|
- Similar to IslandViewer but for groups
|
||||||
|
- Member list, roles, group posts
|
||||||
|
- Join/Leave functionality
|
||||||
|
- Admin panel for owners
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What's Next (TODO)
|
||||||
|
|
||||||
|
### Phase 1: Full-page Islands
|
||||||
|
1. When clicking an island in Universe, replace map with IslandViewer (full page)
|
||||||
|
2. Add back button to return to map
|
||||||
|
3. Show island posts in a feed format
|
||||||
|
4. Allow posting content to island
|
||||||
|
|
||||||
|
### Phase 2: Planet Viewer
|
||||||
|
1. Create PlanetViewer component (similar to IslandViewer)
|
||||||
|
2. Show planet info, members list, posts
|
||||||
|
3. Join/Leave buttons
|
||||||
|
4. Member management for admins
|
||||||
|
|
||||||
|
### Phase 3: Island Apps & Documents
|
||||||
|
1. Widget system for islands (apps)
|
||||||
|
2. Document storage/display
|
||||||
|
3. Customizable island layout
|
||||||
|
4. Drag-drop island editing
|
||||||
|
|
||||||
|
### Phase 4: Planet Features
|
||||||
|
1. Planet channels (like Discord)
|
||||||
|
2. Planet roles and permissions
|
||||||
|
3. Planet events
|
||||||
|
4. Planet announcements
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Swarm Services
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Current running services
|
||||||
|
backend_core-api sociowire/core-api:planets-v1
|
||||||
|
sociowire_island-service sociowire/island-service:planets-v1
|
||||||
|
users_island-service sociowire/island-service:planets-v1
|
||||||
|
sociowire_frontend sociowire/frontend:v103
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Files to Edit
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `src/components/Island/IslandUniverse.jsx` | Universe modal with tabs |
|
||||||
|
| `src/components/Island/IslandViewer.jsx` | Island full-page view |
|
||||||
|
| `src/components/Island/PlanetViewer.jsx` | Planet full-page view (CREATE) |
|
||||||
|
| `src/api/client.js` | API functions |
|
||||||
|
| `src/App.jsx` | Route handling, modal state |
|
||||||
|
| `src/styles/universe.css` | Universe styles |
|
||||||
|
| `src/styles/island.css` | Island styles |
|
||||||
|
| `src/locales/*/translation.json` | Translations |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Islands are auto-created when user registers (linked to user)
|
||||||
|
- Planets must be explicitly created by users
|
||||||
|
- Both use MapLibre GL for 3D terrain rendering
|
||||||
|
- Terrain is procedurally generated from seed
|
||||||
|
- Universe shows all islands/planets floating in space
|
||||||
|
- Backend uses YugabyteDB (Postgres-compatible)
|
||||||
Loading…
Reference in New Issue