6.6 KiB

Raw Blame History

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)

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)

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

// 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

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

When clicking an island in Universe, replace map with IslandViewer (full page)
Add back button to return to map
Show island posts in a feed format
Allow posting content to island

Phase 2: Planet Viewer

Create PlanetViewer component (similar to IslandViewer)
Show planet info, members list, posts
Join/Leave buttons
Member management for admins

Phase 3: Island Apps & Documents

Widget system for islands (apps)
Document storage/display
Customizable island layout
Drag-drop island editing

Phase 4: Planet Features

Planet channels (like Discord)
Planet roles and permissions
Planet events
Planet announcements

Swarm Services

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

6.6 KiB Raw Blame History