Flow Docs

overview

9 min read

Flow - Event Discovery Platform

Executive Summary & Project Overview

Version: 1.0.0 Last Updated: March 10, 2026 Status: Active Development / MVP Phase

Vision & Mission

Vision: Become the leading platform for discovering authentic, personalized events that foster meaningful connections and community building in urban areas.

Mission: Transform how people discover and experience events by combining AI-driven personalization, social networking, and real-time engagement in a single, elegant mobile-first platform.

Product Value Propositions

For End Users

  • AI-Powered Discovery: Personalized event recommendations based on interests, behavior, and location
  • Social Connection: Find like-minded people, create squads, and attend events together
  • Gamification: Earn points, unlock badges, and access exclusive events based on engagement
  • Real-Time Updates: Live event information, instant messaging, and presence indicators
  • Unified Experience: All event information aggregated in one beautiful, easy-to-use app

For Event Organizers (Vendors)

  • Targeted Reach: Access users most likely to be interested in their events
  • Management Tools: Create, manage, and promote events from web dashboard or mobile app
  • Analytics: Real-time insights on event performance, attendance, and engagement
  • Direct Communication: Engage with attendees through notifications and messages
  • Revenue Opportunities: Ticketing integration and promotional features

For Community & Venues

  • Brand Building: Establish presence as event destination
  • Customer Insights: Understand visitor demographics and preferences
  • Event Calendar: Manage multiple events across different dates and times
  • Reputation System: Build trust through reviews and ratings

Market Opportunity

Target Market

  • Primary: Urban millennials and Gen-Z (18-35 years old)
  • Secondary: Established professionals and young families (35-50 years old)
  • Geographic Focus: Starting with Reggio Emilia, Italy; expanding to other European cities

Market Size

  • Global event management software market: $18.6B (projected 2025)
  • Mobile event discovery segment: $5.1B (projected 2025)
  • Growth rate: 16.8% CAGR

Competitive Advantages

  1. AI-First Approach: Advanced ML recommendations vs. basic filtering
  2. Social Integration: Built-in community features vs. standalone event listings
  3. Local Focus: Deep market penetration vs. broad shallow coverage
  4. Gamification: Engagement mechanics vs. passive browsing
  5. Real-Time: Live updates and messaging vs. static information

Technology Stack

Mobile Application

  • Framework: Flutter 3.x (Dart)
  • State Management: Riverpod
  • Navigation: GoRouter
  • Backend: Supabase (PostgreSQL + Auth)
  • Real-time: Socket.IO client
  • Notifications: Firebase Cloud Messaging
  • Local Storage: Hive, Flutter Secure Storage

Admin Portal

  • Framework: Next.js 16 (React 19)
  • Styling: Tailwind CSS 4
  • State: TanStack Query
  • Forms: React Hook Form + Zod validation
  • Tables: TanStack Table
  • Charts: Recharts, Chart.js
  • Backend: Supabase (same as mobile)

Backend Microservices

  • Runtime: Node.js 18+ with Express.js
  • Architecture: Microservices pattern with API Gateway
  • Databases:
    • MongoDB (operational data for microservices)
    • PostgreSQL/Supabase (admin portal & mobile app)
    • Redis (caching, sessions, queues)
    • Elasticsearch (search indexing)
  • Real-time: Socket.IO with Redis adapter
  • Message Queue: Bull (Redis-based)

AI/ML Services

  • Framework: Python 3.9+ with FastAPI
  • ML Libraries: TensorFlow, Scikit-learn, Pandas
  • Services: Recommendation engine, User matchmaking

Infrastructure

  • Containers: Docker, Docker Compose
  • CI/CD: GitHub Actions
  • Hosting:
    • Vercel (Admin Portal)
    • Self-hosted or cloud (Backend services)
    • Supabase Cloud (Database & Auth)

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                            │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │  Flutter Mobile  │  │  Admin Portal    │  │  Future Web  │  │
│  │  (iOS/Android)   │  │  (Next.js)       │  │  Client      │  │
│  └────────┬─────────┘  └────────┬─────────┘  └──────┬───────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
            │ ┌──────────────────▼────────────────────▼─┐
            │ │      SUPABASE (PostgreSQL)              │
            │ │  Auth, Profiles, Events, Venues, etc.   │
            │ └─────────────────────────────────────────┘
            │
            │
┌───────────▼─────────────────────────────────────────────────────┐
│                      API GATEWAY (Port 3000)                    │
│        Rate Limiting, Auth, Routing, WebSocket Proxy            │
└──┬────────┬─────────┬──────────┬──────────┬────────────────────┘
   │        │         │          │          │
   ▼        ▼         ▼          ▼          ▼
┌────────┐┌──────┐┌────────┐┌────────┐┌────────────┐
│  User  ││Event ││Social  ││Notif.  ││ Realtime   │
│Service ││Svc   ││Service ││Service ││ Service    │
│ :3001  ││:3002 ││ :3003  ││ :3004  ││ :3005      │
└────┬───┘└───┬──┘└───┬────┘└───┬────┘└─────┬──────┘
     │        │       │         │           │
     └────────┴───────┴─────────┴───────────┼──────────┐
                                            │          │
     ┌──────────────────────────────────────▼──┐   ┌───▼────────┐
     │         DATA LAYER                       │   │  AI Layer  │
     │  ┌──────────┐ ┌────────┐ ┌───────────┐  │   │ ┌────────┐ │
     │  │ MongoDB  │ │ Redis  │ │Elasticsrch│  │   │ │Recomm. │ │
     │  │(Ops Data)│ │(Cache) │ │  (Search) │  │   │ │:8001   │ │
     │  └──────────┘ └────────┘ └───────────┘  │   │ └────────┘ │
     └──────────────────────────────────────────┘   │ ┌────────┐ │
                                                    │ │Match   │ │
                                                    │ │:8002   │ │
                                                    │ └────────┘ │
                                                    └────────────┘

Project Structure

Flow/
├── mobile/flow_app/              # Flutter mobile app
│   ├── lib/
│   │   ├── core/                 # Core utilities, services, network
│   │   ├── features/             # Feature modules (auth, events, social)
│   │   ├── shared/               # Shared widgets and notifiers
│   │   └── main.dart
│   └── pubspec.yaml
│
├── admin-portal/                 # Next.js admin & vendor dashboard
│   ├── app/                      # App router pages
│   │   ├── admin/                # Admin-specific pages
│   │   └── vendor/               # Vendor-specific pages
│   ├── components/               # Reusable React components
│   ├── lib/                      # Utilities, API clients, schemas
│   └── package.json
│
├── backend/                      # Node.js microservices
│   ├── api-gateway/              # API Gateway (port 3000)
│   ├── user-service/             # User management (port 3001)
│   ├── event-service/            # Event CRUD (port 3002)
│   ├── social-service/           # Social features (port 3003)
│   ├── notification-service/     # Notifications (port 3004)
│   └── realtime-service/         # WebSocket/Socket.IO (port 3005)
│
├── ai-services/                  # Python AI/ML services
│   ├── recommendation-engine/    # Event recommendations (port 8001)
│   └── matchmaking-service/      # User matching (port 8002)
│
├── supabase/                     # Supabase migrations and config
│   └── migrations/               # SQL migration files
│
├── docs/                         # **Documentation (this folder)**
│   ├── PROJECT_OVERVIEW.md       # This file
│   ├── TECHNICAL_ARCHITECTURE.md # Detailed technical specs
│   ├── API_DOCUMENTATION.md      # API endpoints and contracts
│   ├── DATABASE_SCHEMA.md        # Database models and relationships
│   ├── DEPLOYMENT_GUIDE.md       # How to deploy
│   ├── DEVELOPMENT_GUIDE.md      # How to develop
│   └── ROADMAP.md                # Product roadmap
│
├── scripts/                      # Utility scripts
├── infrastructure/               # Docker, K8s configs
├── .env.example                  # Environment template
├── docker-compose.yml            # Local development setup
└── README.md                     # Quick start guide

Key Features

Core Features (MVP - Current Phase)

  • ✅ User authentication & authorization (Supabase Auth)
  • ✅ User profiles with preferences
  • ✅ Event discovery and browsing
  • ✅ Event creation and management
  • ✅ Venue management
  • ✅ Category-based filtering
  • ✅ Location-based search (PostGIS)
  • ✅ Admin dashboard with analytics
  • ✅ Vendor portal for event organizers
  • ⏳ Real-time messaging (Socket.IO - in progress)
  • ⏳ Push notifications (Firebase - in progress)
  • ⏳ Event reviews and ratings (schema ready)

Social Features (Phase 2)

  • ⏳ Friend connections
  • ⏳ Squads (temporary event groups)
  • ⏳ Social feed
  • ⏳ Group creation and management
  • ⏳ User matchmaking
  • 📋 Event comments and discussions

Gamification (Phase 2-3)

  • ⏳ Points system (karma)
  • 📋 Badges and achievements
  • 📋 Leaderboards
  • 📋 Reputation-based event access
  • 📋 Exclusive event invitations

AI Features (Phase 3)

  • 📋 Personalized event recommendations
  • 📋 User compatibility matching
  • 📋 Smart event suggestions
  • 📋 Predictive attendance modeling

Advanced Features (Phase 4)

  • 📋 Ticketing integration
  • 📋 Payment processing
  • 📋 Advanced analytics for organizers
  • 📋 Multi-language support (i18n ready)
  • 📋 Campaign management
  • 📋 PR/Media tracking
  • 📋 Guest feedback system

Legend: ✅ Implemented | ⏳ In Progress | 📋 Planned

Business Model

Revenue Streams

  1. Freemium Model

    • Free: Basic event discovery and attendance
    • Premium: Advanced features, priority support, exclusive events

  2. Vendor Subscriptions

    • Free tier: Limited events per month
    • Pro tier: Unlimited events, advanced analytics
    • Enterprise: Multi-venue, white-label options

  3. Transaction Fees

    • Small percentage on paid event tickets
    • Payment processing fees

  4. Advertising

    • Sponsored event placement
    • Featured venue listings
    • Banner ads (non-intrusive)

  5. Data & Insights

    • Aggregated market insights for businesses
    • Trend reports (anonymized data)

Development Roadmap

Phase 1: MVP (Current - Q1-Q2 2026)

Goal: Launch functional app in Reggio Emilia

  • ✅ Core infrastructure setup
  • ✅ User authentication & profiles
  • ✅ Event CRUD operations
  • ✅ Admin & vendor portals
  • ⏳ Real-time messaging
  • ⏳ Push notifications
  • ⏳ Mobile app refinement
  • ⏳ Beta testing with local users

Phase 2: Social Features (Q3 2026)

Goal: Build community engagement

  • Friend connections & social graph
  • Squads for group event attendance
  • User-to-user messaging
  • Event reviews and ratings
  • Basic recommendation engine
  • Gamification v1 (points, badges)

Phase 3: AI & Scale (Q4 2026 - Q1 2027)

Goal: Scale to 3-5 cities

  • Advanced AI recommendations
  • User matchmaking algorithms
  • Multi-city deployment
  • Performance optimizations
  • Advanced analytics dashboard
  • Mobile app v2.0

Phase 4: Monetization & Growth (Q2-Q4 2027)

Goal: Achieve profitability

  • Ticketing integration
  • Payment processing
  • Premium features
  • Advertising platform
  • International expansion
  • Enterprise features

Success Metrics (KPIs)

User Metrics

  • DAU/MAU ratio: Target 30%+
  • User retention: 40% D7, 25% D30
  • Session duration: Avg 10+ minutes
  • Events viewed per session: 5+

Engagement Metrics

  • Event attendance rate: 15%+ of interested users
  • Social connections: Avg 10+ per active user
  • Reviews submitted: 30%+ of attendees
  • Share rate: 20%+ of events viewed

Business Metrics

  • Vendor acquisition: 100 active venues in 6 months
  • Event creation: 500+ events/month
  • GMV (Gross Merchandise Value): Track ticket sales
  • Revenue: Target $50K MRR by end of Year 1

Technical Metrics

  • Uptime: 99.9%+
  • API latency: p95 < 200ms
  • Error rate: < 0.1%
  • Build success rate: > 95%

Team & Organization

Development Team Structure

  • Frontend: Mobile (Flutter) + Web (Next.js)
  • Backend: Microservices (Node.js) + Database
  • AI/ML: Recommendation systems (Python)
  • DevOps: Infrastructure, monitoring, deployment
  • Product: UX/UI design, feature planning
  • QA: Testing, quality assurance

Development Practices

  • Agile/Scrum: 2-week sprints
  • Version Control: Git with feature branches
  • Code Review: Required before merge
  • CI/CD: Automated testing and deployment
  • Documentation: Comprehensive and up-to-date
  • Testing: Unit, integration, E2E coverage

Risk Assessment

Technical Risks

  • Database Complexity: MongoDB + PostgreSQL dual-database approach
    • Mitigation: Clear data boundaries, CDC for sync if needed
  • Microservices Overhead: Distributed system complexity
    • Mitigation: Strong observability, well-defined contracts
  • Real-time Scalability: Socket.IO scaling challenges
    • Mitigation: Redis adapter, horizontal scaling, proper load balancing

Business Risks

  • User Acquisition: Chicken-and-egg problem (users need events, organizers need users)
    • Mitigation: Seed with manual event curation, partner with local venues
  • Competition: Established players (Eventbrite, Facebook Events)
    • Mitigation: Focus on local niche, superior UX, AI personalization
  • Revenue: Delayed monetization
    • Mitigation: Low burn rate, focus on retention over premature monetization

Operational Risks

  • Data Privacy: GDPR compliance, user data protection
    • Mitigation: Privacy by design, regular audits, secure infrastructure
  • Scalability: Growth beyond initial capacity
    • Mitigation: Cloud-native architecture, monitoring, auto-scaling

Next Steps

Immediate Priorities (Next 30 Days)

  1. ✅ Fix Vercel deployment issues
  2. ⏳ Complete real-time messaging implementation
  3. ⏳ Implement push notifications
  4. ⏳ Mobile app beta testing
  5. ⏳ Organize and update all documentation
  6. ⏳ Set up monitoring and observability

Short Term (Next 90 Days)

  1. Launch MVP to limited user base in Reggio Emilia
  2. Gather user feedback and iterate
  3. Implement social features (Phase 2)
  4. Optimize performance and fix bugs
  5. Prepare for wider launch

Medium Term (Next 6-12 Months)

  1. Scale to 3-5 additional cities
  2. Build AI recommendation engine
  3. Implement gamification features
  4. Launch monetization features
  5. Grow user base to 50K+ users

Contact & Resources

Documentation

Support

  • Issues: GitHub Issues
  • Discussions: GitHub Discussions
  • Email: [Configure team email]

Last Updated: March 10, 2026 Document Owner: Development Team Next Review: April 10, 2026

Graph View