Sector Tagger

Visual editor for creating, managing and tagging sectored layouts. Built with modern web technologies including Bun, Astro, Svelte 5, SQLite, and WebSocket for real-time collaboration.

Features

Interactive canvas for visual layout management
Hierarchical structure (pages -> views -> sectors)
Real-time collaboration via WebSocket
Offline support with LocalStorage
SQLite database for persistent storage
SSL/HTTPS support
Docker support for easy deployment

Tech Stack

Runtime: Bun - Fast JavaScript runtime
Framework: Astro - Modern web framework
UI Library: Svelte 5 - Reactive UI framework
Database: SQLite with Drizzle ORM
Real-time: WebSocket for live updates
Development: TypeScript for type safety

Project Structure

sector-tagger/
├── certs/                    # SSL certificates
│   ├── cert.pem
│   └── key.pem
├── data/                     # Data directory
│   └── db.sqlite            # SQLite database
├── scripts/                  # Helper scripts
│   ├── init-db.ts           # Database initialization
│   ├── start-dev.sh         # Development startup
│   └── ws-server.ts         # WebSocket server
├── src/
│   ├── assets/              # Static assets
│   ├── components/          # Svelte components
│   │   ├── BaseSector.svelte     # Base sector component
│   │   ├── HoverPanel.svelte     # Hover information panel
│   │   ├── SelectedPanel.svelte  # Selected item details
│   │   ├── Tagger.svelte         # Main canvas component
│   │   └── TransformHandle.svelte # Transform controls
│   ├── layouts/             # Astro layouts
│   ├── lib/                 # Core library code
│   │   ├── api/            # API and WebSocket
│   │   │   ├── types.ts           # API types
│   │   │   ├── webSocketServer.ts # WS server
│   │   │   └── websocketClient.ts # WS client
│   │   ├── config.ts       # App configuration
│   │   ├── db/            # Database
│   │   │   ├── index.ts    # DB exports
│   │   │   ├── migrate.ts  # Migrations
│   │   │   └── schema.ts   # DB schema
│   │   └── storage/       # Storage handlers
│   │       └── localStore.ts # Local storage
│   ├── pages/              # Astro pages
│   │   └── index.astro    # Main page
│   ├── styles/            # Global styles
│   └── types/             # TypeScript types
├── .env                    # Environment variables
├── .env.example           # Environment template
├── astro.config.mjs       # Astro configuration
├── docker-compose.yml     # Docker Compose config
├── Dockerfile            # Docker build config
└── package.json          # Project metadata

Key Components

Canvas System

Tagger.svelte: Main canvas component managing the layout editor
BaseSector.svelte: Base component for all sector types (pages, views, sectors)
Hierarchical rendering with proper z-index handling

Real-time Collaboration

WebSocket server for live updates
Client-side WebSocket integration
Event synchronization across clients

Data Management

SQLite database for persistent storage
Drizzle ORM for type-safe database operations
LocalStorage for offline capabilities

UI Components

HoverPanel: Shows quick info on hover
SelectedPanel: Detailed information for selected items
TransformHandle: Controls for item manipulation

Environment Variables

# Server Configuration
VITE_SERVER_HOST=localhost
VITE_SERVER_PORT=3000
VITE_SERVER_PROTOCOL=https

# WebSocket Configuration
VITE_WS_HOST=localhost
VITE_WS_PORT=4321
VITE_WS_PATH=/api/ws

# SSL Configuration
VITE_SSL_KEY_PATH=./certs/key.pem
VITE_SSL_CERT_PATH=./certs/cert.pem

# Database Configuration
VITE_DB_PATH=./data/db.sqlite

# Development Mode
VITE_DEV_MODE=true

Development

Clone the repository
Install dependencies:
```
bun install
```
Set up environment variables:
```
cp .env.example .env
```

Generate SSL certificates (for HTTPS):

mkdir certs
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout certs/key.pem -out certs/cert.pem

Initialize database:
```
bun run scripts/init-db.ts
```
Start development server:
```
bun run dev
```

Docker Deployment

Build and run with Docker Compose:
```
docker compose up --build
```

The application will be available at:

Frontend: https://localhost:3000
WebSocket: wss://localhost:4321

Architecture

Data Flow

User interactions on canvas trigger events
Events are processed locally and sent to WebSocket server
Server broadcasts events to all connected clients
Clients update their state and re-render affected components
Changes are persisted to SQLite database

State Management

Svelte stores for reactive state
LocalStorage for offline persistence
WebSocket for real-time sync
SQLite for permanent storage

Security

HTTPS/WSS for secure communication
Environment variables for configuration
SSL certificate management

License

MIT License - see LICENSE file for details

PaznerA/sector-tagger-svelte