Aqua Stark Backend API

Backend API for Aqua Stark, an on-chain game based on Starknet.

This backend orchestrates all actions between:

• Unity (frontend)
• Cartridge (authentication)
• Supabase (off-chain data)
• Dojo + Cairo contracts (on-chain)

Quick Start

Prerequisites

• Node.js >=20.10.0
• npm or yarn

Installation

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your credentials

# Development
npm run dev

# Build
npm run build

# Production
npm start

Documentation

All documentation is available in the /docs directory:

• Getting Started - Setup and development guide
• Deployment - Deployment guide for all environments
• Architecture - System architecture and design
• Standards - Coding standards and conventions
• Error Handling - Error management system
• Models - Data model guidelines
• Responses - Response system documentation

Technology Stack

Technology	Version	Purpose
Node.js	>=20.10.0	JavaScript runtime
TypeScript	5.3.x	Type safety
Fastify	4.29.x	HTTP framework
Supabase JS	2.38.3	Database and storage
Starknet.js	5.14.x	Blockchain interactions
Dojo Client	1.8.5	On-chain ECS

Project Structure

/src
├── api/                  # Routes grouped by resource
├── controllers/          # Request handlers
├── services/             # Business logic
├── models/               # Domain entities
└── core/
    ├── types/            # Shared types (LOCKED)
    ├── errors/           # Custom error classes
    ├── responses/         # Response helpers (LOCKED)
    ├── middleware/        # Global middleware
    ├── utils/             # Utility functions
    └── config/            # Configuration

Important Standards

The response system is locked. All endpoints MUST use:

• createSuccessResponse() for successful responses
• createErrorResponse() for errors
• ControllerResponse<T> as return type

See Standards and Responses for details.

Environment Variables

Required environment variables (see .env.example):

• SUPABASE_URL - Your Supabase project URL
• SUPABASE_KEY - Supabase anonymous key
• STARKNET_RPC - Starknet RPC endpoint
• CARTRIDGE_AUTH_URL - Cartridge authentication URL

Development

# Development mode with hot-reload
npm run dev

# Type checking
npm run type-check

# Build for production
npm run build

Available Scripts

• npm run dev - Start development server
• npm run build - Compile TypeScript to JavaScript
• npm start - Start production server
• npm run type-check - Verify types without compiling

Contributing

1. Read Getting Started for setup
2. Follow Standards for coding conventions
3. Use strict TypeScript types
4. All endpoints must follow the standard response format