Saga

A social coordination platform for meaningful connections.

Overview

Saga combines the best elements of community platforms:

• Guilds - Social groups with shared activities and contacts
• Adventures - Multi-day, multi-location coordination for groups
• Events - Host-controlled gatherings with concrete times and places
• Discovery - Find compatible people through questionnaire matching
• Trust Network - Event-anchored trust ratings with endorsements

Architecture

saga/
├── admin/            # Deno Fresh admin web app
├── api/              # Go backend (SurrealDB, REST API, SSE)
│   ├── cmd/          # Application entrypoints
│   ├── internal/     # Private application code
│   ├── migrations/   # Database migrations
│   ├── openapi/      # API specification
│   └── docs/         # Technical documentation
├── ios/              # SwiftUI iOS app
└── .github/          # CI/CD workflows

Tech Stack

Component	Technology
Backend	Go 1.23 with Chi router
Database	SurrealDB 3.0.0-beta.3
Auth	JWT + Passkeys (WebAuthn) + OAuth
iOS	SwiftUI, iOS 17+
Admin	Deno Fresh (TypeScript)
CI/CD	GitHub Actions

Quick Start

Prerequisites

• Go 1.23+
• Docker and Docker Compose
• Make
• Xcode 16+ (for iOS)

Setup

# Clone and setup
git clone https://github.com/forgo/saga.git
cd saga
make setup

# Start development environment
make dev

# Run tests
make test

Commands

Command	Description
make setup	First-time developer setup
make dev	Start API and SurrealDB
make stop	Stop all services
make test	Run all tests
make lint	Lint all code
make dev-admin	Start admin dev server
make test-admin	Run admin tests

Local Development

Running the Full Stack

1. Start API with seed data:

   make dev          # Starts API + SurrealDB

2. Run iOS app pointing to local API:

   • Open ios/Saga/Saga.xcodeproj
   • Environment defaults to development (localhost:8080)
   • Use demo credentials to login (see below)

Demo Users

The API seed data includes test users for development:

Email	Password	Description
demo@forgo.software	password123	Primary user with guilds & data
second@forgo.software	password123	Secondary user for testing

iOS Testing Modes

The iOS app supports launch arguments for testing:

Argument	Description
--uitesting	Enables UI test mode
--demo	Auto-login with demo user

Running E2E Tests

# Terminal 1: Start API
make dev

# Terminal 2: Run iOS UI tests
cd ios/Saga
xcodebuild test -scheme Saga -destination 'platform=iOS Simulator,name=iPhone 16 Pro,OS=18.6'

# To see available simulators:
xcrun simctl list devices available

Documentation

API Documentation

Document	Description
OpenAPI Spec	REST API specification (OpenAPI 3.1)
ARCHITECTURE.md	System design and layers
DATABASE.md	Database patterns and queries
FEATURES.md	Feature implementation guide
SCHEMA.md	Database schema reference
SECURITY.md	Security model and access control
PERFORMANCE.md	Performance tuning
DEVELOPMENT.md	Development status and TODOs

Project Documentation

Document	Description
SAGA.md	Product vision and feature design
CHANGELOG.md	Release history
CONTRIBUTING.md	Contribution guidelines
VERSIONING.md	API versioning strategy

iOS Documentation

Document	Description
ios/README.md	iOS app setup and architecture

API Endpoints

The API uses URL path versioning (/v1/...). Key endpoints:

Authentication:
  POST /v1/auth/register     - Email/password registration
  POST /v1/auth/login        - Login with credentials
  POST /v1/auth/passkey/*    - Passkey authentication
  GET  /v1/auth/oauth/*      - OAuth flows

Guilds:
  GET  /v1/guilds            - List user's guilds
  POST /v1/guilds            - Create guild
  POST /v1/guilds/{id}/join  - Join guild

Trust:
  POST /v1/trust-ratings     - Create trust rating
  GET  /v1/trust-ratings/*   - Query trust ratings

Real-time:
  GET  /v1/guilds/{id}/events - SSE event stream

Admin:
  GET    /v1/admin/users              - List users (paginated, search, filter)
  GET    /v1/admin/users/{id}         - User detail with profile + moderation
  PATCH  /v1/admin/users/{id}/role    - Update user role
  DELETE /v1/admin/users/{id}         - Soft delete (ban) or hard delete
  POST   /v1/admin/seed/*             - Seed test data
  POST   /v1/admin/actions/*          - Trigger actions as users

Full specification: api/openapi/openapi.yaml

Admin Console

The admin console (/admin) is a Deno Fresh web app for managing the platform:

• Users — Search, filter, and manage user accounts. Change roles, view profiles, suspend/ban users, and delete accounts via a slide-over detail panel.
• Data Seeder — Generate mock users, guilds, and events for testing.
• Actions — Trigger events as simulated users for real-time testing.
• Discovery Lab — Test the discovery algorithm visually on a map.

make dev-admin    # Start admin dev server at http://localhost:5173

Testing

The project includes 306 tests across 18 domains:

# Run all tests
make test

# Run specific domain tests
go test -v ./tests/... -run TestAuth
go test -v ./tests/... -run TestGuild
go test -v ./tests/... -run TestTrust

# With coverage
make test-coverage

Test domains: Auth, Guilds, Trust, Voting, Adventures, Resonance, Events, Discovery, Activities, People, Timers, Roles, Moderation, Visibility, Location Privacy, Matching Pools, Compatibility, Forums.

Release Process

Releases are automated via GitHub Actions:

1. Update CHANGELOG.md
2. Create and push a tag: git tag v1.2.3 && git push --tags
3. CI runs tests, builds binaries, publishes Docker image

See VERSIONING.md for versioning policy.

Contributing

See CONTRIBUTING.md for:

• Development setup
• Code architecture
• Testing requirements
• Pull request process
• Commit message format

License

MIT License - see LICENSE for details.