my_openplace/frontend-src/README.md

FurryPlace Frontend Source

Reconstructed SvelteKit frontend for FurryPlace, based on analysis of compiled production build.

Quick Start

# Install dependencies
pnpm install

# Set up environment
cp .env.example .env

# Run development server
pnpm dev

# Build for production
pnpm build

Project Structure

src/
├── lib/
│   ├── api/
│   │   └── client.ts           # API client with all backend endpoints
│   ├── constants/
│   │   ├── config.ts           # App configuration
│   │   └── colors.ts           # 64-color palette
│   ├── stores/
│   │   ├── global.ts           # Global state (turnstile, language, time)
│   │   ├── user.ts             # Current user + auth
│   │   ├── canvas.ts           # Canvas/map state
│   │   ├── alliance.ts         # Alliance state
│   │   └── toast.ts            # Toast notifications
│   ├── utils/
│   │   ├── bitmap.ts           # Bitmap for unlocked colors/flags
│   │   ├── charges.ts          # Charge regeneration calculations
│   │   └── level.ts            # Level/XP calculations
│   ├── components/            # To be created
│   └── i18n/                  # To be created
├── routes/                    # SvelteKit routes (to be created)
└── app.css                    # TailwindCSS + DaisyUI styles

Features Implemented

✅ Core Infrastructure

• API client with all backend endpoints
• Svelte stores for state management
• Utility functions (bitmap, charges, levels)
• Constants (colors, config, store items)

🚧 In Progress

• i18n translation system (EN/PT)
• UI components
• Auth pages
• Canvas/map implementation
• Admin/moderation panels

Tech Stack

• SvelteKit 2.x - Framework
• TypeScript - Type safety
• TailwindCSS - Utility-first CSS
• DaisyUI 4.x - Component library
• Leaflet - Map/canvas
• Cloudflare Turnstile - Bot protection

Key Patterns

API Calls

import { api } from '$lib/api/client';

// Fetch user profile
const user = await api.getMe();

// Paint pixels
await api.paintPixels('s1', tileX, tileY, {
  colors: [7, 7, 7],
  coords: [[100, 100], [101, 100], [102, 100]]
});

Stores

import { currentUser, isAuthenticated } from '$lib/stores/user';
import { toast } from '$lib/stores/toast';

// Subscribe to user
$: user = $currentUser;

// Show notification
toast.success('Welcome!');

Colors

import { COLOR_PALETTE, getColorHex, isColorUnlocked } from '$lib/constants/colors';

const hex = getColorHex(7); // '#ed1c24'
const unlocked = isColorUnlocked(32, user.extraColorsBitmap);

Environment Variables

PUBLIC_API_URL=http://localhost:3000
PUBLIC_SEASON=s1

Next Steps

1. Create i18n translation system
2. Build common components (Button, Modal, Toast, etc.)
3. Create Turnstile component
4. Build auth/login page
5. Implement main canvas with Leaflet
6. Create alliance, leaderboard, store pages
7. Build admin and moderation panels

Development Notes

• Uses DaisyUI's light theme only
• Pixelated rendering for tile images
• Charge regeneration updates every 500ms
• JWT auth via j HttpOnly cookie
• OAuth providers: Google, Twitch

See IMPLEMENTATION_NOTES.md for detailed findings from compiled frontend analysis.