Architecture Overview

TrickBook follows a client-server architecture with a shared backend serving the mobile app, website, and Chrome extension. Real-time features are powered by Socket.IO, and an AI companion layer (Kaori) provides conversational assistance via tool-calling, RAG, and text-to-speech.

System Diagram

Components

For cross-repo service boundaries and endpoint ownership, see Repo Dependency Map.

Mobile App (TrickList)

The React Native application built with Expo SDK 54 and TypeScript. Uses Expo Router for file-based navigation and NativeWind for Tailwind CSS styling.

Key Features:

• Trick list management (create, edit, track progress)
• Trickipedia (global trick encyclopedia)
• Spot discovery with map view, reviews, and ratings
• Homies (friend system with requests and profiles)
• Social feed with video/photo uploads, reactions, and comments
• The Couch (curated action sports video library)
• Direct messaging (real-time via Socket.IO)
• Kaori AI companion chat with voice responses
• User profiles with stats and activity feed
• Stripe subscription management

Chrome Extension (Map Scraper)

A Chrome extension that extracts skate spot data from Google Maps and syncs it to TrickBook.

Key Features:

• One-click spot extraction from Google Maps
• Automatic geocoding for city/state
• Tag categorization (bowl, street, lights, etc.)
• Spot list management
• Bulk sync to TrickBook backend
• CSV export for offline use

See Chrome Extension for full documentation.

Backend API

Express.js REST API with Socket.IO for real-time features. Handles all business logic, data persistence, and third-party integrations.

Responsibilities:

• User authentication (JWT + Google OAuth + Apple Sign-In)
• CRUD operations for all resources
• Social feed with algorithmic scoring
• Real-time messaging and feed updates (Socket.IO)
• Image upload to AWS S3
• Video streaming via Bunny.net CDN
• Stripe subscription management
• Push notifications via Expo
• Google Places spot search
• Kaori AI companion with tool-calling (search spots, trickipedia, user data)

Kaori AI Services

The AI companion layer consists of three services that work together to provide conversational, tool-augmented interactions. See Kaori Architecture for a deep dive.

Kaori Bot Server (Port 3001):

• ElizaOS-based agent with a defined character and personality
• Tool-calling loop: searches spots, queries trickipedia, reads user tricklists, remembers user info
• Relationship tracking via companion_profiles (adjusts tone based on friendship stage)
• RAG context injection from PostgreSQL (boardsport knowledge base)

OpenRouter API:

• Routes LLM requests to Gemini 2.0 Flash
• Handles the tool-calling protocol (function definitions, tool results, multi-turn)

Kith Voice (Port 3040):

• Text-to-speech sidecar using ElevenLabs via Pipecat runtime
• WebSocket bridge: browser connects via WS, backend sends text via HTTP POST
• Per-session subprocess model for isolated audio streaming

Real-Time Layer (Socket.IO)

WebSocket server providing real-time features via namespaces.

Namespaces:

• /feed -- Live post updates, reaction counts, comment notifications
• /messages -- Real-time message delivery, typing indicators, read receipts

Databases

TrickBook uses a dual-database architecture: MongoDB for application data and PostgreSQL for vector search (RAG).

Dual-database rationale

MongoDB handles all transactional application data (users, tricks, spots, feed, messages). PostgreSQL with pgvector provides embedding-based semantic search for the Kaori AI knowledge base, which requires vector similarity queries that MongoDB does not natively support.

MongoDB Atlas

Cloud-hosted MongoDB database storing all application data.

Collections:

• users -- User accounts, subscriptions, homie connections
• tricklists -- User's personal trick lists
• tricks -- Individual tricks in lists
• trickipedia -- Global trick encyclopedia
• spotlists -- User's spot collections
• spots -- Skate spot locations
• spot_reviews -- User reviews and ratings for spots
• spot_trick_history -- Tricks landed at specific spots
• feed_posts -- Social feed posts with media
• reactions -- Love/respect reactions on posts
• feed_comments -- Comments on feed posts
• saved_posts -- User bookmarked posts
• conversations -- Direct message conversations
• dm_messages -- Individual messages
• bot_chats -- AI companion chat messages
• companion_profiles -- AI companion relationship tracking
• blog -- Website blog content
• categories -- Trick categories
• expoPushTokens -- Push notification tokens

PostgreSQL (pgvector)

Vector database for Kaori's retrieval-augmented generation (RAG) pipeline.

Tables:

• Boardsport knowledge embeddings (magazine articles, trick guides, culture content)
• Queried at chat time to inject relevant context into Kaori's system prompt

AWS S3

Object storage for user-uploaded images.

Buckets:

• trickbook -- Profile images, trick images, spot images

Bunny.net CDN

Video streaming and delivery for media content.

Features:

• Video library management
• Signed URL generation for protected content
• CDN delivery via b-cdn.net

Stripe

Payment processing for premium subscriptions.

Products:

• Free tier (limited spot lists and spots)
• Premium monthly subscription ($10/month -- unlimited access)
• Premium yearly subscription

Data Flow

Authentication Flow

Real-Time Connection Flow

Shared Backend Considerations

The backend serves multiple clients:

Client	Base URL	Auth	Real-time
iOS App	api.thetrickbook.com	JWT (x-auth-token)	Socket.IO
Android App	api.thetrickbook.com	JWT (x-auth-token)	Socket.IO
Website	api.thetrickbook.com	JWT	Socket.IO
Chrome Extension	api.thetrickbook.com	JWT	N/A

warning

Any API changes must maintain backwards compatibility with all clients. The website now uses Socket.IO for direct messaging, so changes to the /messages namespace affect three platforms (iOS, Android, Web).