🍝 Agora POS

A free and open source Point of Sale system for Italian Food Festivals

Built with ❤️ for Sagre, Fiere, and community food events across Italy

Features • Screenshots • Quick Start • Tech Stack • Structure • Contributing

---

🎯 What is Agora?

Agora is a modern, offline-first POS (Point of Sale) application designed specifically for Italian Sagre (food festivals), Fiere (fairs), and community events. Whether you're serving porchetta, arrosticini, piadine, or vino locale, Agora helps you manage orders, track inventory, and serve customers faster.

📍 Why "Agora"? — Named after the ancient Greek marketplace, Agora represents the heart of community gatherings where food, culture, and people come together.

---

✨ Features

📱 Point of Sale

• Fast order entry — Optimized touch interface for high-volume service
• Product categories — Organize items by course (Primi, Secondi, Dolci, Bevande)
• Modifier groups — Handle customizations (size, toppings, cooking preferences)
• Quick checkout — Complete transactions in seconds

📦 Inventory Management

• Real-time stock tracking — Know exactly what you have left
• Low stock alerts — Never run out of popular items mid-service
• Batch adjustments — Quickly update quantities after restocking

🧾 Order Management

• Order history — Complete transaction records
• Order status tracking — Pending, Completed, Voided
• Line item details — Track each product with modifiers
• Notes & special requests — Handle customer preferences

💰 Financial Tracking

• Subtotals & grand totals — Accurate calculations in cents
• Tax calculation — Configure for local regulations
• Discount support — Apply promotions and special offers

👥 Workforce Management

• Employee accounts & PIN login — Fast operator switching at the counter
• Roles & permissions — Cassiere, Admin, and custom roles
• Clock-in / clock-out — Track shifts per employee

🧾 Guided Onboarding

• First-run setup wizard — Business type and profile configuration
• Capability-driven experience — Nav and POS adapt to the business profile chosen

🖨 Receipt Printing

• ESC/POS thermal printing — Bluetooth/USB receipt printers

🌐 Multi-Platform

• Android — Tablets and phones
• iOS — iPads for elegant counter setup
• Web — Browser-based access for flexibility

🔒 Offline-First

• Local SQLite database — Works without internet
• Sync when connected — Never lose a sale
• Fast & reliable — No network latency

---

📸 Screenshots

Screenshots coming soon — Stay tuned! 🎬

---

🚀 Quick Start

Prerequisites

• FVM (Required — manages the pinned Flutter SDK version, see .fvmrc)
• Melos (dart pub global activate melos) — manages the monorepo workspace
• Android Studio / Xcode for mobile development

Installation

# Clone the repository
git clone https://github.com/fres-sudo/agora.git
cd agora

# Bootstrap the monorepo (links all packages, runs pub get)
melos bootstrap

# Generate code (Freezed, Drift, AutoRoute, etc.) across all packages
melos run build

# Run the app
cd apps/agora && fvm flutter run

Configuration

# Generate translations (per-package, uses Slang)
cd packages/i18n && fvm flutter pub run slang

# Generate assets
cd apps/agora && fvm flutter pub run flutter_gen

# Generate launcher icons
cd apps/agora && fvm flutter pub run flutter_launcher_icons

---

🛠 Tech Stack

Category	Technology
Framework	Flutter 3.38+
Monorepo tooling	Melos
State Management	BLoC + flutter_bloc
Local Database	Drift (SQLite)
Navigation	auto_route
DI & Architecture	Pine (service locator) + Provider
Models	Freezed + json_serializable
Internationalization	Slang
HTTP Client	Dio
Logging	Talker
Feature flags	package:feature_flags
Receipt printing	esc_pos_utils_plus (ESC/POS)

---

📁 Project Structure

Agora is a Melos-managed Flutter monorepo with three scopes:

agora/
├── apps/
│   └── agora/                 # Flutter entry point (no business logic)
│       └── lib/app/           # bootstrap, provider assembly, routing
│
├── features/                  # Domain-isolated feature packages
│   ├── auth/                  # Authentication & session management
│   ├── onboarding/             # First-run business setup wizard
│   ├── products/               # Product catalog management
│   ├── orders/                 # Order processing
│   ├── inventory/               # Stock management
│   ├── discounts/                # Promotions & pricing rules
│   ├── pos/                       # Point of Sale interface
│   ├── reports/                    # Sales analytics & reporting
│   ├── settings/                    # App configuration
│   └── workforce/                    # Employees, roles, PIN login, clock-in
│       └── lib/
│           ├── data/            # Drift DAOs, DTOs, repository impls
│           ├── domain/          # Freezed models, repository interfaces, mappers
│           └── presentation/    # Blocs, pages, widgets, route registration
│
└── packages/                  # Cross-cutting infrastructure (no business logic)
    ├── ui_kit/                 # Design system, shared widgets
    ├── theme/                  # AppTheme, ThemeCubit
    ├── database/                # AgoraDatabase (Drift), central schema
    ├── sync_engine/              # Offline-first sync primitives
    ├── printing/                  # Receipt building & ESC/POS thermal printing
    ├── feature_flags/              # Business type / capability flags
    ├── i18n/                        # Slang-generated translations
    ├── bloc/                         # flutter_bloc + freezed re-exports
    ├── result/                        # Result<T, E> pattern
    ├── errors/                         # AppException, RepositoryException
    ├── logger/                          # Talker wrapper
    ├── observer/                         # BlocObserver
    ├── remote_config/                     # Remote config abstraction
    ├── app_info/                           # App/package version info
    ├── config/                              # Environment/flavor config
    ├── launcher/                             # App launcher icon generation
    ├── utils/                                 # Extensions, constants
    └── design_lint/                            # Custom lint rules for the design system

Each feature package follows a strict presentation → domain ← data layering. See CONTRIBUTING.md and docs/architecture/ for the full architectural spec, dependency rules, and the multi-app/backend roadmap.

---

🤝 Contributing

We welcome contributions from the community! Please read our Contribution Guidelines and Code of Conduct before getting started.

Quick Commands

# Run tests across all packages
melos run test

# Analyze code across all packages
melos run lint

# Format code across all packages
melos run format

# Full CI quality gate (format + lint + design lint + test)
melos run ci

---

📋 Roadmap

• 🖨 Receipt printing (ESC/POS thermal printers)
• 👥 Multi-user support with roles (Cassiere, Admin) & PIN login
• 🧭 Guided onboarding & business-profile setup
• 📊 Sales analytics & reporting dashboard
• 🔄 Cloud sync via the Agora backend (Go + PostgreSQL)
• 📱 Kitchen display system (KDS) app
• 🧍 Self-order totem & customer mobile app
• 💳 Payment integration (SumUp, Satispay)
• 🎫 Ticket/token system for Sagre

See docs/architecture/ECOSYSTEM.md for the full multi-app/backend build-phase plan.

---

📄 License

Agora is released under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means you're free to:

• ✅ Use the software for any purpose
• ✅ Study and modify the source code
• ✅ Distribute copies
• ✅ Distribute your modifications

With the requirement that:

• 📝 You must disclose your source code if you run a modified version on a server

---

💬 Community & Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• 📧 Contact: me@fres.space

---

Made in Italy 🇮🇹 for Italian Sagre everywhere

_{If Agora helped your event, consider giving us a ⭐ on GitHub!}