Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
103 lines (79 loc) · 4.35 KB

ARCHITECTURE.md

File metadata and controls

103 lines (79 loc) · 4.35 KB
Raw

GuildWorkman architecture

A short map of how the system fits together, so a new contributor knows where their change lives before they start. For per-repo detail, read that repo's own README.

The shape of it

GuildWorkman is split across two repositories along one deliberate boundary — the client, and the thing the client has to trust.

                guildworkman-web  (Next.js / React / TypeScript)
                        │
                        │  REST over HTTPS
                        ▼
        guildworkman-core
        ├── backend-api/         Spring Boot (Java 17) + PostgreSQL
        │                        auth · worker directory · appointment lifecycle
        │                        (single source of truth today)
        │
        └── soroban-contracts/   Rust / Soroban  — WRITTEN, NOT YET WIRED IN
            ├── escrow           holds payment until a job is confirmed
            ├── reputation       one immutable review per completed job
            └── loyalty-token    SEP-41-style rewards token

guildworkman-web

The client-facing app. Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS v4. Mobile-first, because the audience is on mid-range Android phones over unreliable data.

It holds no business logic and no persistent state. It renders what the backend returns and sends back what the user does, talking to the backend over REST at NEXT_PUBLIC_API_BASE_URL. A Freighter wallet-connect button is already integrated (@stellar/freighter-api), but the app makes no smart contract calls yet.

Routes cover the full marketplace: landing, login, client/worker signup, profile management, and the book / cancel / update / view appointment flows.

guildworkman-core

A two-package monorepo holding the two things that must be trustworthy.

backend-api/ — the Spring Boot service

Java 17, Spring Boot 3.3, PostgreSQL, JWT auth, Cloudinary for profile media, Paystack for payments today. It is the single source of truth for who a user is and what state a booking is in, and it defines the REST contract the frontend is written against.

Layered structure, package root com.guildworkman.api:

controllers/   REST endpoints
services/      interfaces (ServiceUtils/) + implementations (implmentations/)
               and the Paystack integration (paystack/)
data/models/   JPA entities
dto/           request/response payloads
config/        security, mail, cloud, mapper
handler/       global exception handling

Request flow: Controller → Service interface → ServiceImpl → JPA repository, DTOs mapped via ModelMapper, responses wrapped in a standard envelope.

soroban-contracts/ — the on-chain trust layer

Three independent Soroban contracts (soroban-sdk 26.1), each with its own storage, upgrade path, and trust boundary:

  • escrow — holds a client's payment for a booked appointment until the client confirms the job is done; releases to the worker, refunds on cancellation, supports admin-arbitrated disputes.
  • reputation — stores one immutable review per completed appointment and a running rating aggregate per worker.
  • loyalty-token — a SEP-41-style token minted (by the backend's service account) to reward completed appointments.

They mirror domain logic that exists in the backend today (AppointmentService, ReviewService, TransactionService), moving the trust-sensitive parts — holding money, recording reviews, issuing rewards — on-chain.

What's live vs. what's ahead

This is the honest current state, and it's where most contribution effort goes:

  • Live: the marketplace end to end — signup, login, browse, book, cancel, accept/decline, profile management — plus a real Freighter wallet connection. Payments run through Paystack against the backend.
  • Written, not wired: the Soroban contracts are implemented and unit-tested, but not deployed to a network and not called from the backend or the frontend. Closing that gap — deploy to testnet, generate bindings, add Soroban RPC + keypair handling to the backend, hold/release escrow around a real booking, write outcomes to reputation — is the roadmap.

CI

  • guildworkman-web — lint, type-check, and build on every PR.
  • guildworkman-core — path-filtered: backend changes run the Maven workflows, soroban-contracts/** changes run the Soroban workflow.