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