Crew Messaging

A bilingual SMS/MMS messaging dashboard for landscaping companies featuring automatic audio transcription, AI-powered translation, and an iMessage-like interface.

Overview

Crew Messaging streamlines communication with multilingual teams by automatically transcribing and translating all messages. Crew members text in their native language via SMS/MMS, while administrators see conversations in English with one-click translation and reply capabilities.

Key Features

• Bilingual SMS/MMS: Receive and send messages in multiple languages (Spanish, Portuguese, English)
• Automatic Transcription: Voice messages are transcribed to text using OpenAI Whisper
• AI Translation: Messages automatically translate between crew's language and English
• Audio Recording: Admins can record voice replies that are translated and sent via SMS
• Media Support: Display images and voice messages from MMS
• Group Messaging: Broadcast messages to multiple crew groups with automatic deduplication
• Role-Based Access: Owner → Admin → Crew Leaders → Crew Members hierarchy
• Crew Management: Add crew members, organize into groups, manage invitations
• Persistent Storage: Cloud-based audio/image storage via object storage
• Message Search: Full-text search across conversations with date filtering

Tech Stack

Frontend

• React 18 with TypeScript
• Vite for development and bundling
• TailwindCSS + shadcn/ui for styling
• React Query (TanStack Query) for state management
• Wouter for routing
• Lucide React for icons

Backend

• Node.js with Express
• PostgreSQL (Neon serverless) with Drizzle ORM
• Multer for file uploads
• JWT for authentication
• Passport.js for local authentication

External Services

• Twilio: SMS/MMS messaging and webhooks
• OpenAI:
  • Whisper API for speech-to-text
  • GPT-4o-mini (with GPT-4o fallback) for translation
• Object Storage: Persistent storage for audio files and images

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• Twilio account with SMS capabilities
• OpenAI API key
• Supabase Storage for media files

Installation

1. Clone the repository

   git clone <repository-url>
   cd crew-messaging

2. Install dependencies

   npm install

3. Set up environment variables Create a .env.local file with:

   DATABASE_URL=<your-database-url>
   OPENAI_API_KEY=<your-openai-key>
   SESSION_SECRET=<your-session-secret>
   JWT_SECRET=<your-jwt-secret>
   DEFAULT_OBJECT_STORAGE_BUCKET_ID=<storage-bucket-id>
   PUBLIC_OBJECT_SEARCH_PATHS=<public-storage-paths>
   PRIVATE_OBJECT_DIR=<private-storage-directory>
   

4. Run database migrations

   npm run db:push

5. Start the development server

   npm run dev

   The app will be available at http://localhost:5000

Architecture

Data Models

Users

• Roles: owner, admin, department_head, crew_leader, crew_member
• JWT-based authentication with explicit role field
• Profile management with phone numbers

Crews

• Phone number (receives SMS)
• Preferred language (es, pt, en)
• Status: active, pending (awaiting CONFIRM reply)
• Optional role assignment (crew_leader, admin)

Messages

• Direction: inbound, outbound
• Type: text, voice, image
• Original text + language detection
• Translations to English
• Transcripts (for voice messages)
• Delivery status tracking: pending, sent, delivered, failed

Crew Groups

• Created and managed by department heads
• Contains multiple crew members
• Leader assignment for crew leaders

API Structure

Authentication

• POST /api/auth/login - User login
• POST /api/auth/logout - User logout

Conversations

• GET /api/conversations - List conversations
• GET /api/conversations/:crewId - Get conversation thread
• POST /api/send-message - Send message to crew

Crew Management

• GET /api/crews - List crew members
• POST /api/crews - Add crew member
• PATCH /api/crews/:id - Update crew member
• DELETE /api/crews/:id - Remove crew member
• POST /api/crews/:id/resend-invite - Resend invitation

Crew Groups

• GET /api/crew-groups - List groups
• POST /api/crew-groups - Create group
• PATCH /api/crew-groups/:id - Update group
• DELETE /api/crew-groups/:id - Delete group

Twilio Webhooks

• POST /api/webhook/message - Inbound SMS/MMS handler
• Automatically transcribes audio, detects language, translates content

Message Flow

Inbound (Crew → Admin)

1. Crew member sends SMS/MMS to shared number
2. Twilio webhook receives message
3. If audio: Whisper transcribes to text
4. GPT-4o-mini detects language & translates to English
5. Message stored in database
6. Admin sees translated message in dashboard

Outbound (Admin → Crew)

1. Admin composes message in English (text or voice)
2. If voice: Uploaded to storage, Whisper transcribes
3. GPT-4o-mini translates to crew's preferred language
4. SMS sent via Twilio to crew's phone
5. Delivery status tracked and updated

User Roles & Access

Dashboard Login Access (Web App)

Owner

• Login: ✅ Yes
• Account: System admin account (set up during initial deployment)
• Dashboard sees:
  • All crew members across all groups
  • All conversations from all crews
  • All users (admins, department heads, crew leaders)
  • Can send messages to any crew member
  • Can manage all crew members and groups
  • Can assign roles to any user
  • Can delete any crew member or admin account
  • Can view and manage all department heads

Admin

• Login: ✅ Yes
• Account: Created by owner, credentials sent via SMS after "CONFIRM" reply
• Dashboard sees:
  • All crew members and conversations (or filtered set if owner pre-assigned filters)
  • Can send messages to crew members
  • Can manage crew members (add, edit, delete, resend invites)
  • Can create crew groups
  • Cannot assign roles to users
  • Cannot manage other admins

Department Head (Production Manager)

• Login: ✅ Yes
• Account: Created by owner, credentials sent via SMS after "CONFIRM" reply
• Dashboard sees:
  • Only the crew groups they created (their own teams)
  • Only crew members they personally invited to their groups
  • Cannot see other department heads' crews
  • Cannot see system-wide crew member pool
  • Can send messages to their crew members only
  • Can manage their own crew members only (add, edit, delete, resend invites)
  • Can create new crew groups
  • Cannot assign roles to users
  • Cannot access other department heads' data

Crew Leader

• Login: ❌ No
• Account: No web login access
• SMS Access: Receives SMS invitations and can text in conversations
• Management Access: Via department head/admin only:
  • Can be assigned to one specific crew group
  • Can send/receive SMS messages within their group
  • Can be managed (edited, removed) by admins or their department head
  • Cannot access web dashboard

Crew Member

• Login: ❌ No
• Account: No web login access
• SMS Access Only:
  • Receives initial invitation SMS
  • Sends/receives SMS messages in conversations
  • Messages automatically translate between their language and English
  • Can record voice messages
  • No dashboard access

User Workflow

1. Invite Crew Member: Admin adds phone number via dashboard
2. SMS Invitation: System sends "Reply CONFIRM to join" SMS
3. CONFIRM Reply: Crew member replies with CONFIRM
4. Account Creation: User account created, credentials sent via SMS
5. Active Member: Member can now send/receive messages

Mobile Optimization

The dashboard is fully responsive with:

• Optimized touch targets for mobile (48px minimum)
• 16px base font size for readability
• Floating action buttons for primary actions
• Simplified layouts for small screens
• iMessage-style message bubbles

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

For issues, feature requests, or questions, please contact: hello@crew-messaging.com

---

Version: 1.0.0
Last Updated: December 2025