Open Wearables Platform Architecture

​

Repository Structure

open-wearables/
├── backend/          # FastAPI Python backend
│   ├── app/
│   │   ├── api/     # API routes and endpoints
│   │   ├── models/  # SQLAlchemy database models
│   │   ├── schemas/ # Pydantic request/response schemas
│   │   ├── services/# Business logic layer
│   │   ├── repositories/ # Data access layer
│   │   └── integrations/ # Third-party integrations (Celery, Sentry)
│   ├── migrations/  # Alembic database migrations
│   └── scripts/     # Utility and initialization scripts
├── frontend/        # SvelteKit developer portal
│   ├── src/
│   │   ├── routes/     # Pages, loaders and form actions
│   │   └── lib/        # Components, domain logic, server-only API client
│   └── e2e/            # Playwright tests against a mock API
├── mcp/            # MCP server (Beta) - AI assistant integration
│   └── app/
│       ├── tools/     # MCP tool definitions
│       └── services/  # API client for backend communication
└── docs/            # Mintlify documentation

​

Runtime Stack

​

Backend

• FastAPI (Python 3.14+) - Modern, fast web framework with automatic OpenAPI documentation
• SQLAlchemy 2.0 - ORM for database interactions
• Alembic - Database migration management
• Pydantic - Data validation and settings management

• PostgreSQL 18 - Primary relational database
• Redis 8 - Task queue broker and caching

• Celery - Distributed task queue for background jobs
• Celery Beat - Scheduled task execution
• Flower - Celery monitoring and administration

• python-jose - JWT token handling
• bcrypt - Password hashing
• cryptography - Encrypted provider settings storage

• Docker & Docker Compose - Containerization and orchestration
• Sentry - Error tracking and monitoring

​

Frontend

• SvelteKit 2 / Svelte 5 - Server-rendered routing, loaders and form actions
• Bun - Runtime and package manager
• Vite - Build tool and dev server

• Tailwind CSS 4 - Utility-first styling with design tokens
• Lucide - Icon library
• Charts are hand-drawn SVG; dialogs are native <dialog> elements

• API tokens live in an HttpOnly cookie that page scripts cannot read; only the frontend server calls the API

• Vitest - Unit tests, and component tests in a real browser
• Playwright - End-to-end tests against a production build

​

MCP Server (Beta)

• FastMCP - MCP server framework for AI assistant integration
• httpx - Async HTTP client for backend API communication
• Pydantic - Settings and data validation

• Natural language queries for health metrics (sleep, workouts, etc.)
• User discovery and data retrieval tools
• Unified data format regardless of wearable provider

Note: The MCP server is currently in beta and is actively being developed.

​

Architecture Patterns

​

Backend Architecture

1. API Layer (app/api/routes/) - HTTP endpoints and request handling
2. Service Layer (app/services/) - Business logic and orchestration
3. Repository Layer (app/repositories/) - Data access abstraction
4. Model Layer (app/models/) - Database schema definitions

​

Data Flow

Client Request
    ↓
API Route (FastAPI)
    ↓
Service Layer (Business Logic)
    ↓
Repository Layer (Data Access)
    ↓
Database (PostgreSQL)

​

Background Processing

API Endpoint
    ↓
Celery Task Queue (Redis)
    ↓
Celery Worker
    ↓
Provider API / Webhook Delivery

​

Deployment Architecture

• app - FastAPI application server
• db - PostgreSQL database
• redis - Redis cache and message broker
• celery-worker - Background task processor
• celery-beat - Scheduled task scheduler
• flower - Celery monitoring dashboard
• frontend - SvelteKit developer portal, served by Bun

• Single-tenant architecture (one deployment = one organization)
• No external dependencies for core functionality
• All services can run locally with docker compose up
• Stateless application servers (horizontal scaling ready)

​

Development Workflow

• Hot-reload enabled via Docker Compose watch mode
• Database migrations via Alembic
• Code quality enforced with Ruff & ty

• Vite HMR (Hot Module Replacement) for instant updates
• TypeScript strict mode, checked by svelte-check
• ESLint and Prettier