Skip to main content

Backend Architecture

This backend is a Node.js + TypeScript service with GraphQL, HTTP endpoints, background workflows, and Prisma persistence.

Stack​

  • Runtime: Node.js (CommonJS), TypeScript
  • API Layer: GraphQL + Express routes
  • Persistence: Prisma (@prisma/client)
  • Workflows: state-machine style engines under src/core/workflow
  • Integrations: Stripe, Paymob, Twilio, push notifications, email templates

High-Level Layers​

src/server*​

  • Bootstraps Express/GraphQL server and middleware.
  • Wires route registration and app startup concerns.

src/data​

  • GraphQL schema composition and resolvers.
  • Permission checks, query/mutation handlers, and GraphQL object types.

src/application​

  • Service layer and repository interfaces.
  • Encapsulates use-case logic, independent from ORM-specific details.

src/infrastructure/prisma​

  • Concrete repository implementations and unit-of-work wiring.
  • Translates domain/application calls into Prisma operations.

src/core​

  • Domain-heavy modules:
    • reservation/document workflows
    • payment orchestration
    • email rendering/sending
    • cron tasks
    • sockets and notifications

src/libs and src/helpers​

  • Shared runtime utilities, middleware, external service wrappers, and helpers.

Request Lifecycle (GraphQL)​

  1. Request enters GraphQL server in src/server.
  2. Resolver in src/data/queries or src/data/mutations validates input and permissions.
  3. Resolver calls application services/repositories through unit-of-work context.
  4. Prisma repositories execute DB access.
  5. Side effects (notifications, emails, workflow transitions) are triggered from services/core modules.
  6. Resolver returns typed response shape.

Workflow Architecture​

  • Workflow definitions live in:
    • src/core/workflow/ReservationWorkflow.ts
    • src/core/workflow/DocumentApprovalWorkflow.ts
  • Shared abstractions:
    • BaseWorkflow
    • WorkflowDispatcher
    • WorkflowHandler
    • types.ts
  • Generated docs:

Documentation Source of Truth​

  • Human-authored architecture/operations docs in apps/backend/docs.
  • Auto-generated workflow/notification docs from scripts in apps/backend/scripts.
  • Auto-generated TypeScript API docs from TypeDoc in apps/backend/docs/api.