festappnet/festapp

Festapp

Festapp is a cross-platform mobile and web app for festivals, conferences, and events. It provides organizers and attendees with powerful tools like schedules, maps, notifications, tickets, forms, and much more.

Festapp powers vstupenky.online — a full-featured ticketing and eshop platform for event organizers to sell tickets, manage orders, and handle payments.

• Try now on live.festapp.net or install to your phone here.
• Visit us on website: festapp.net
  
  Alt text

---

Features

• Available on Android, iOS, and Web.
• Event is available for offline use (Android, iOS, Web/PWA).
• Dark and light modes are available.
• Volunteer Management: Dedicated staffing system for managing tasks, shifts, and assignments.

---

• Schedule
  • Timeline – Schedule overview by time and day.
  • Event detail – Includes: Time, Place (with link), Content, Subevents, Sign In/Sign Out button.
  • Timetable – View event entries on the axes of Time and Place.
  • My schedule – Attendee can add event entries to their own list.

schedule2 schedule1 schedule5 schedule3

• Map
  • Map with current user location, places, and paths with custom icons and descriptions. It is also possible to set up an offline map (Android, iOS).

map1 map2 map4

• News/Notifications
  • Receive news and push notifications relevant to the event.
  • Push notifications are supported on all platforms – Android, iOS, and Web.

news3 news2

• Info/Songbook/Game

  • Various information about the event, a Songbook with font-size increase/decrease, and a groups-based code-guessing game.

• Administration/Feature settings

  • Overview of all event data, map, groups, users, rights, and other settings.
  • Setup of multiple events.

• User/Companions/Workshops

  • User profile with personal data.
  • Ability to import users from a table.
  • Creation of events with limited capacity (workshops) and creation of companions.
  • QR code for workshop entry verification.

user1 user3 user4 user5

• Ticket/Form/Seat reservation
  • Support for creation of custom forms (similar to Google Forms) with priced products.
  • Creation of custom tickets with custom graphics.
  • Creation of a seat reservation component.

form1 form3 form4 form5

• Orders/Transactions

  • Order management, bank payment synchronization, automated sending, and creation of paid tickets.

• Email Templates

  • Customization of all email templates.

email1 email2 email3

• Ticket scanning
  • QR-code-based ticket verification.

---

Architecture

This project is built using the Flutter framework and the Dart programming language.

The backend uses the Supabase stack across managed-cloud and self-hosted targets during the current cutover. It includes:

• Deno functions written in TypeScript
• PostgreSQL scripts for database operations

graph TD
    A["Flutter App<br/>(Android / iOS / Web)"] -->|Supabase SDK| S
    B["Web Client<br/>(Vanilla JS)<br/>Forms, Blueprint"] -->|REST API / RPC| S
    C["Cloudflare Pages Worker<br/>routing, SEO, sitemap"] -->|REST API / RPC| S
    W["Cloudflare Workers<br/>client sync, image control"] -->|RPC| S
    W --> R2["Cloudflare R2<br/>sync and image objects"]
    A -->|immutable sync artifacts| W

    S["Supabase Platform"]
    S --- Auth
    S --- Storage
    S --- EF["Edge Functions (Deno)"]
    S --- RT[Realtime]
    S --- PG["PostgreSQL<br/>SQL functions (RPC) · RLS · SECURITY DEFINER"]

Key Architectural Highlights:

• Offline-First: The app is designed to work fully offline (critical for festivals). It uses a robust caching strategy (OfflineDataService) and local databases.
• SQL-Centric Logic: A significant portion of business logic (orders, games, permissions) resides in PostgreSQL Functions (RPC) rather than Dart code.
• Multi-Tenant: Supports multiple organizations, units, and occasions with role-based access control managed by RightsService.
• Dual Frontend: The Flutter app serves mobile/web, while a standalone vanilla JS web client (web_client/) handles public-facing forms, blueprints, and ticket ordering.

[!TIP] For Developers & AI Agents:
Please consult these architectural documents:

• docs/architecture/ai_context.md - Architecture overview, directory structure, and component patterns
• docs/architecture/SERVICES.md - Critical data services (RightsService, OfflineDataService, SynchroService)
• docs/architecture/database.md - Database structure, SQL functions, and security patterns
• docs/backend/edge_functions.md - Supabase Edge Functions reference

Also see: CONTRIBUTING.md for testing, security checklist, and commit workflow.

---

Configuration

The project uses a centralized configuration system driven by automation/project.conf. This file is the single source of truth for:

• Deployment: Domain settings (DOMAIN, CNAME).
• Application: Supabase credentials (SUPABASE_URL, ANON_KEY), Organization ID, and integration links.
• Theme: Brand colors (THEME_SEED_1...4) which are automatically applied to both Flutter (app_config.dart) and Web Client (theme_config.css).
• Fonts: Font family configuration (FONT_FAMILY_BASE) and form scaling.
• Version: Application version (VERSION), propagating to pubspec.yaml, package.json, and the app.

Applying Configuration

After editing automation/project.conf, apply changes by running:

./automation/apply_config.sh

This script automatically:

1. Updates all relevant configuration files.
2. Auto-detects and installs fonts from automation/fonts/.
3. Synchronizes version numbers.

---

Setup

For a helpful step-by-step guide on creating your own app, see docs/setup/howto.md.

---

Deployments

Festapp deployments are tenant-specific. Shared application and release tooling live on main; each prod/* branch contains only its approved configuration and brand overlay. Web releases use direct Cloudflare Pages upload and are never triggered by a branch push alone. See tenant overlays and the Cloudflare deployment guide.

---

Latest Development

See CHANGELOG.md for the full development history.

Follow updates on the Festapp WhatsApp Channel (in Czech).

---

Testing

Run the full test suite with a single command:

./automation/test_all.sh

This runs Web Client, database, Flutter, Edge Function, integration and automation tests. Environment-dependent suites report when required local tools or credentials are absent. Database tests execute inside transactions and auto-rollback, so no fixture data is retained.

For more details on testing, deployment, and the security audit checklist, see CONTRIBUTING.md.

---

Development

Prerequisites

• FVM (Flutter Version Management): FLUTTER_VERSION in automation/project.conf is the canonical SDK pin; apply_config.sh propagates it to FVM and editor configuration.
  • Install FVM: dart pub global activate fvm
  • Install project SDK: fvm install

Running the Flutter App

Always prefix flutter/dart commands with fvm:

# Get dependencies
fvm flutter pub get

# Run on Chrome
fvm flutter run -d chrome

# Run code generation
fvm dart run build_runner build --delete-conflicting-outputs

Running the Web Client

The standalone web client (forms, blueprints, ticket ordering) lives in web_client/:

cd web_client
npm install
npm run dev    # Development server
npm test       # Run tests

Project Structure

festapp/
├── lib/                    # Flutter app (Dart)
│   ├── components/         # Feature modules
│   ├── data_services/      # Business logic & data access
│   ├── services/           # Helper services (time, toast, notifications)
│   └── database_tables/    # Table name constants (Tb class)
├── database/               # PostgreSQL logic
│   ├── functions/          # SQL functions (organized by domain)
│   ├── migrations_legacy/  # Historical pre-Supabase upgrade fragments
│   ├── policies/           # Row Level Security policies
│   ├── tables/             # Table definitions
│   ├── tests/              # SQL regression tests
│   └── seed/               # Initial data
├── supabase/
│   ├── baseline/           # Versioned schema-only local bootstrap
│   ├── migrations/         # Active forward migrations
│   └── functions/          # Deno Edge Functions (TypeScript)
├── workers/                # Cloudflare Workers (sync, images, monitoring)
├── web_client/             # Standalone JS web client
│   ├── src/components/     # UI components (forms, blueprint, ticket ordering)
│   ├── src/services/       # Client services (auth, router, supabase, theme, localization, etc.)
│   ├── scripts/            # Build & test utilities
│   └── tests/              # Unit and integration tests
├── automation/             # Config, build, deploy scripts
│   ├── project.conf        # Single source of truth for configuration
│   ├── apply_config.sh     # Propagates config to all targets
│   └── hetzner-supabase/   # Self-hosted Supabase tooling and runbooks
└── netlify/                # Legacy retirement adapters and regression tests

For detailed project architecture and internal documentation, please refer to the documentation map and AI context.

---

About

The app was originally developed by a team of volunteers for Absolventský Velehrad event in 2023.