Mobayilo Web App - Project Summary

Project overview

Build a mobile-first, browser-based international calling web app:

Users sign up with email/password
Users top-up credits (pay-as-you-go)
Users place outbound calls from the browser (WebRTC) to real phone numbers (PSTN)

Website: https://mobayilo.com

Core MVP features

Authentication (email/password, password reset)
Company seats (passwordless magic links)
Credits wallet (balance in cents) + transaction ledger
Stripe top-ups (one-time credit purchases)
Optional auto top-up (threshold-based)
Dialer UI (mobile-first) + Twilio Voice JS SDK
Recent numbers (server-side, per account)
Twilio webhooks validated + processed asynchronously
Call logging (status, duration) and cost deduction after completion
Rate lookup (price/min) by destination
Static pricing table (YAML) with company vs individual rates

Technical stack (target)

Backend: Ruby on Rails 8.1
Frontend: Hotwire (Turbo + Stimulus) + Tailwind CSS
Database: PostgreSQL
Voice: Twilio Programmable Voice (WebRTC to PSTN)
Payments: Stripe (PaymentIntent + webhooks)

Design system

Color Palette

Token	Hex	Usage
`action-green`	`#22C55E`	Primary buttons, active states, call to action
`action-green-hover`	`#16A34A`	Hover states for primary actions
`dark-bg`	`#0F172A`	Main application background (Dark Mode)
`dark-card`	`#1E293B`	Card backgrounds, panel backgrounds
`dark-card-alt`	`#162032`	Secondary/Layered backgrounds
`white`	`#FFFFFF`	Primary text, icons
`gray-300`	`#D1D5DB`	Secondary text, muted descriptors

Typography

Role	Font Family	Variable	Usage
Headings	Cormorant Garamond	`font-heading`	Page titles, hero text, logo
Body	Inconsolata	`font-body`	Interface text, buttons, inputs
Code	Geist Mono	`font-mono`	Code snippets, technical logs

UI Standards

Buttons:
- Radius: rounded-2xl
- Vertical Padding: py-3 (standard), py-2 (compact)
- Horizontal Padding: px-6 (standard)
Icons:
- Library: Lucide / Heroicons (SVG)
- Stroke: stroke-width="2"
- Color: currentColor (inherit text color)
Layout:
- Mobile: Full-screen “App” experience, bottom navigation (clustered right), hidden header/footer using md:hidden.
- Desktop: SaaS landing page experience, standard navbar/footer using md:block.

MVP decisions

Billing: per-started-minute.
Jobs: Solid Queue (Rails default).
Rate source: YAML table served via /api/rates/:iso (company seat sees company rates).

Recent changes (2026-01-29)

Mobile app-like shell for Contacts/History/Settings + Credits summary on mobile.
Mobile hamburger menus aligned with design and sign-in overlay kept inside phone frame.
Desktop pricing calculator uses searchable country picker + live rate API.
Admin can sync rates from YAML via Avo action; Twilio sync labeled clearly.
/dial gated behind authentication; public CTAs route to sign-in.
Styled static public/404.html error page aligned with brand.

Architecture (high-level)

Browser (Turbo/Stimulus + Twilio Voice JS)
  ↕ HTTPS
Rails (HTML + JSON endpoints + webhook handlers)
  ↕
PostgreSQL (users, calls, rates, ledger)
  ↕                    ↕
Stripe webhooks        Twilio webhooks + TwiML

Documentation map

docs/PROJECT_STATUS.md - execution checklist and progress
docs/SETUP.md - environment variables + local dev webhooks
docs/PRD.md - requirements and open questions
docs/ARCHITECTURE.md - domain model and routes

Open decisions

Company allowlist: per-email allowlist vs domain-based allowlist
Number provisioning: company admin self-serve vs manual/admin-only (MVP)