# 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)