From ac99f0f1e4b2acb352231b806600e9198f20f9d5 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 24 Jan 2026 18:44:42 +0000 Subject: [PATCH] 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 --- .claude/agents/islands-planets.md | 230 ++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 .claude/agents/islands-planets.md diff --git a/.claude/agents/islands-planets.md b/.claude/agents/islands-planets.md new file mode 100644 index 0000000..d0a183a --- /dev/null +++ b/.claude/agents/islands-planets.md @@ -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)