UpSpace

Coworking space marketplace and booking platform built with Next.js, TypeScript, Prisma, and Supabase.

UpSpace connects customers, remote teams, partners, and administrators through one product surface:

• customers discover coworking spaces, compare inventory, book areas, pay, chat with hosts, bookmark listings, and leave reviews;
• partners create and manage spaces, configure inventory, define pricing rules, submit verification documents, monitor wallets, and request payouts;
• administrators moderate listings, review verifications, reconcile payouts, review complaints and chat reports, and manage user lifecycle actions;
• AI-assisted search and chat-driven booking workflows sit alongside the traditional marketplace flow.

Documentation

The repository now maintains two parallel documentation layers:

• docs/setup.md: local environment setup, database extensions, service configuration, and verification steps.
• docs/architecture.md: application topology, route groups, domain model, and data flow.
• docs/development.md: contribution standards, implementation conventions, testing expectations, and documentation workflow.
• docs/features.md: product behavior by customer, partner, admin, wallet, AI, and moderation domain.
• docs/api-reference.md: generated markdown inventory of all live src/app/api/v1/**/route.ts handlers.
• /docs: Scalar-powered API reference UI rendered from public/openapi.json.
• /openapi.json: machine-readable OpenAPI document generated by pnpm docs:api.

Product Scope

Marketplace and discovery

UpSpace exposes a public marketplace where users can:

• browse published spaces;
• filter by search terms, city, region, and proximity;
• inspect amenities, reviews, availability, and reservable areas;
• use suggestions and AI-assisted search for conversational discovery.

Booking lifecycle

Booking is not just a single insert. The product includes:

• area-level inventory with capacity rules;
• booking lifecycle states such as pending, confirmed, checkedin, checkedout, completed, cancelled, rejected, expired, and noshow;
• rescheduling, receipt retrieval, cancellation, and notification side effects;
• price-rule evaluation for dynamic booking totals.

Partner operations

Partners can:

• create and edit spaces with address, coordinates, amenities, images, and weekly availability;
• manage areas and booking requirements;
• define pricing rules instead of legacy base-rate rows;
• submit, resubmit, and withdraw verification records;
• review complaints, monitor dashboard feeds, inspect stuck bookings, and manage wallet payouts.

Admin operations

Administrators have dedicated route families and dashboard screens for:

• platform metrics and recent operational activity;
• user moderation and account status changes;
• space visibility controls;
• verification review;
• complaint resolution;
• chat-report review;
• payout-request handling;
• reconciliation and audit-oriented finance workflows.

Financial and operational integrations

The application integrates with:

• Supabase for auth, database access, and storage-adjacent workflows;
• PostgreSQL plus PostGIS, trigram search, unaccent, and cryptographic UUID support;
• Xendit for checkout, payouts, and refund-related financial workflows;
• SMTP email delivery for OTP and booking notifications;
• Redis for cache-backed listing acceleration and rate limiting;
• OpenRouter for the AI marketplace assistant.

Stack

Layer	Technology
Web app	Next.js 15 App Router + React 19
Language	TypeScript in strict mode
Styling	Tailwind CSS + shadcn/ui
Data access	Prisma ORM
Database	PostgreSQL via Supabase
Search and geo	pg_trgm, unaccent, PostGIS
Auth	Supabase Auth
Client data	React Query
Validation	Zod
Payments and payouts	Xendit
Tests	Vitest
API docs	Scalar + generated OpenAPI

Repository Layout

Path	Purpose
src/app	App Router pages, layouts, and route handlers
src/app/api/v1	Versioned REST API surface documented in Scalar
src/components	Feature components and shared UI
src/components/ui	shadcn/ui primitives and house wrappers
src/hooks	Reusable client hooks, including API and subscription hooks
src/lib	Business logic, providers, serializers, validation, auth helpers, pricing logic, and AI support
prisma	Prisma schema and migrations
supabase	Supabase-related configuration and supporting assets
tests	Vitest coverage for business logic and integration scenarios
docs	Human-written long-form documentation plus the generated API inventory
scripts/generate-openapi.mjs	Generates both public/openapi.json and docs/api-reference.md

Quick Start

1. Clone and install

git clone https://github.com/ivanreeve/upspace.git
cd upspace
pnpm install

2. Create .env

This repository does not currently ship a checked-in .env.example, so create .env manually and fill in the values documented in docs/setup.md.

At minimum, most local environments need:

DATABASE_URL="postgresql://..."
NEXT_PUBLIC_SUPABASE_URL="https://<project>.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="<anon-key>"
SUPABASE_SERVICE_ROLE_KEY="<service-role-key>"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Feature-complete local development commonly also needs:

NEXT_PUBLIC_GOOGLE_MAPS_API_KEY="<maps-key>"
OPENROUTER_API_KEY="<openrouter-key>"
REDIS_URL="redis://..."
XENDIT_SECRET_KEY="xnd_development_..."
XENDIT_WEBHOOK_VERIFICATION_TOKEN="<token>"
FINANCIAL_DATA_ENCRYPTION_KEY="<long-random-secret>"
EMAIL_SMTP_HOST="smtp.example.com"
EMAIL_SMTP_PORT="587"
EMAIL_SMTP_USER="user"
EMAIL_SMTP_PASSWORD="password"

3. Prepare PostgreSQL

The app expects PostgreSQL with the extensions described in docs/setup.md:

• postgis
• pgcrypto
• pg_trgm
• unaccent
• uuid-ossp

4. Generate Prisma client and run migrations

pnpm prisma generate
pnpm prisma migrate dev

5. Generate API docs

pnpm docs:api

This updates:

• public/openapi.json
• docs/api-reference.md

6. Start the app

pnpm dev

Open http://localhost:3000 for the product and http://localhost:3000/docs for the Scalar API reference.

Daily Commands

Command	Purpose
pnpm dev	Start the App Router development server
pnpm lint	Run ESLint across the repository
pnpm test	Run the Vitest suite
pnpm build	Verify the production build
pnpm docs:api	Regenerate Scalar/OpenAPI and markdown API inventory
pnpm prisma generate	Refresh the Prisma client
pnpm prisma migrate dev	Apply local schema changes

Documentation and API Workflow

The API documentation is no longer hand-maintained as a one-path stub. It is now backed by a repository script:

1. scripts/generate-openapi.mjs walks src/app/api/v1/**/route.ts.
2. It detects live HTTP methods.
3. It enriches routes with domain-specific descriptions, request schemas, and auth notes.
4. It writes the Scalar/OpenAPI source to public/openapi.json.
5. It writes the markdown inventory to docs/api-reference.md.

If you add, delete, rename, or repurpose a route handler, run pnpm docs:api in the same change.

Development Expectations

The codebase standards in AGENTS.md are enforced socially and by tooling:

• TypeScript should remain strict and avoid any.
• Route handlers should validate inputs with Zod before business logic or database writes.
• New UI should use components from @/components/ui/*.
• Decorative icons should come from react-icons.
• User-facing failures should be surfaced clearly, typically through Sonner toasts in the app.
• Raw SQL must stay parameterized and reviewed carefully.
• Documentation is part of the feature surface, not post-work cleanup.

Notable Domain Decisions

• Pricing rules replaced legacy base-rate endpoints. The /spaces/{space_id}/areas/{area_id}/rates* routes still exist only as legacy 410 Gone surfaces.
• Session-aware API routes primarily rely on the Supabase auth session established by the web app rather than custom API keys.
• Partner wallet balances are not manual top-up wallets. Funds flow from booking charges and are reduced by refunds and payouts.
• Verification, moderation, payout review, and reconciliation are explicit platform operations, not hidden admin-only database tasks.

Where To Look Next

• Start with docs/setup.md if you are bringing up a local environment.
• Read docs/architecture.md before large refactors.
• Use docs/development.md when contributing code.
• Use docs/features.md to understand the product behavior expected by each role.
• Use docs/api-reference.md or /docs when working on route handlers or client hooks.

License

This project is licensed under the MIT License. See LICENSE.md.