Suickets

Suickets is an open-source, full-stack decentralized application (dApp) for event ticketing built on the Sui blockchain. It leverages a hybrid on-chain/off-chain architecture to provide a seamless experience for managing both physical and virtual events.

🚀 Overview

Suickets bridges the gap between traditional ticketing systems and Web3. It allows event organizers to create events and sell tickets as NFTs on the Sui network, while managing rich metadata (like venue geolocation) off-chain for performance and flexibility.

Key features include:

• Hybrid Architecture: Combines the security of Sui smart contracts with the flexibility of cloud microservices.
• Gasless Experience (Optional): Implements a "Frontend-Sign, Backend-Execute" pattern, allowing the platform to handle gas fees and execution details.
• Geospatial Discovery: Built-in support for finding physical events near a user using PostGIS.
• Virtual & Physical Support: Flexible event structures supporting both venue-based and online events.

🏗 Architecture

The application is composed of three main layers:

1. Frontend (Astro + React):

   • Located in src/.
   • Handles user interactions, wallet connections, and transaction building.
   • Users sign transactions in the browser, but execution is delegated to the backend.

2. Backend (Node.js on Google Cloud Run):

   • Located in src/cloud-run/functions.
   • tx-api: Receives signed transactions from the frontend, pays gas fees, and submits them to the Sui network.
   • venues-api: Manages venue data and performs geospatial queries via PostGIS.
   • geocode-api: Secure proxy for Google Maps services.

3. Blockchain (Sui Move):

   • Located in src/blockchain/suickets.
   • Contains the EventManager smart contract defining Event and Ticket logic.

The "Frontend-Sign, Backend-Execute" Pattern

To ensure security and manage resources effectively, Suickets uses a specific transaction flow:

1. Build: The Frontend constructs a TransactionBlock.
2. Sign: The User signs the block with their wallet (e.g., Sui Wallet) via @mysten/dapp-kit.
3. Execute: The signed payload is sent to the tx-api backend service, which executes it on the network.

🛠 Tech Stack

• Frontend: Astro, React, Tailwind CSS, @mysten/dapp-kit
• Backend: Node.js, Express, Google Cloud Run
• Blockchain: Sui Move
• Database: PostgreSQL with PostGIS extension

📂 Project Structure

suickets/
├── src/
│   ├── components/          # React UI components (CreateEvent, VenueSelector, etc.)
│   ├── pages/               # Astro pages and API routes
│   ├── blockchain/
│   │   └── suickets/        # Sui Move smart contracts
│   │       ├── sources/     # Move source code
│   │       └── tests/       # Move unit tests
│   └── cloud-run/
│       └── functions/       # Backend microservices
│           ├── tx-api/      # Transaction execution service
│           ├── venues-api/  # Venue management & geospatial search
│           └── geocode-api/ # Google Maps proxy
├── public/                  # Static assets
└── package.json             # Project dependencies

🚦 Getting Started

Prerequisites

• Node.js (v18+)
• Sui CLI
• Docker (optional, for running local DB)

1. Frontend Setup

Install dependencies and start the development server:

Create .env.development and .env.production files from .env.example to support Astro run modes.

npm install
npm run dev

The application will be available at http://localhost:4321.

2. Smart Contract Development

Navigate to the blockchain directory to build and test the Move contracts:

cd src/blockchain/suickets

# Build contracts
sui move build

# Run tests
sui move test

3. Backend Services

The backend services are designed to run on Google Cloud Run. For local development, you can run individual services using Node.js.

Note: Deployment is handled via shell scripts (e.g., deploy-tx-api.sh) which manage secrets and configuration.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines (if available) before submitting a Pull Request.

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

📄 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.