# Commons

> Community-powered digital signage platform for local businesses

Commons is a platform that allows organizations to manage digital ad assets for display on TV-sized screens and smaller devices in retail locations.

## Core Capabilities

- Organization and location management
- Digital slide creation from HTML templates with dynamic content
- Display management for Raspberry Pi-powered screens
- Slideshow delivery with real-time content rotation
- Self-serve ad creation wizard (Activate)
- BSV wallet authentication
- Venue check-in and kiosk experiences
- Community feedback collection
- Badge and embed widgets for external sites

## Tech Stack

- Elixir / Phoenix 1.8 (LiveView)
- PostgreSQL
- Tailwind CSS
- Deployed on Fly.io

## Public Endpoints

- GET / — Homepage
- GET /directory — Public map of organizations and locations
- GET /organizations/:id — Organization public profile
- GET /locations/:id — Location public profile
- GET /about — About page
- GET /pricing — Pricing information
- GET /faq — Frequently asked questions
- GET /developers — Developer information
- GET /community — Community page
- GET /getting-started — Getting started guide

## API Endpoints

- POST /api/displays/:id/heartbeat — Display heartbeat
- POST /api/ads/oneshot — AI-generated one-shot slide creation
- POST /api/auth/wallet/verify — Wallet signature verification
- GET /api/auth/wallet/challenge/:nonce — Wallet auth challenge
- POST /api/ads/:ad_id/impressions — Record ad impression
- GET /api/badges/:token/presence — Badge presence check
- POST /api/badges/:token/collect — Badge analytics collection

## Authentication

- Email/password registration and login
- BSV wallet-based authentication
- Organization invitation system

## Content Model

- **Organizations** have locations and members
- **Locations** belong to organizations and have displays
- **Templates** define HTML layouts with {{variable}} placeholders
- **Slides** are template instances with specific content config
- **Ads** are paid placements of slides with budget, duration, and impression tracking
- **Reels** are ordered collections of slides for display rotation
- **Displays** are physical screens at locations running slideshows