fixit-api: A TypeScript repository from Nerdware

Fixit is a SaaS product that provides users with powerful tools for managing maintenance and repair workflows, including in-app payments powered by Stripe. This repo is home to the dual-protocol Fixit API – built on NodeJS, ExpressJS, and Apollo GraphQL.

Author: Trevor Anderson, Solopreneur & Founder of Nerdware

🗺️ Project Overview
📖 API Schema
- REST Endpoints Diagram
- GraphQL Schema
🔐 User Authentication
💎 Premium SaaS Products
🗄️ DynamoDB Database
- Fixit-API Access Patterns
- Single Table Design
📦 CI/CD Pipeline
📝 License
💬 Contact

🗺️ Project Overview

The Fixit API provides a robust, scalable, and secure backend for the Fixit SaaS product, which provides users with powerful tools for managing maintenance and repair workflows, including in-app payments powered by Stripe.

Note

Quick Links

Fixit REST API OpenAPI
Schema Explorer

Fixit GraphQL API
Schema Explorer

Fixit Frontend
Component Storybook

Fixit Web App
GitHub Repo

📖 API Schema

This API exposes both REST and GraphQL endpoints:

	Schema	Framework	Domain/Purpose
REST API	View OpenAPI Schema	ExpressJS	Handles user authentication, checkout, account management, and webhooks.
GraphQL API	View GQL Schema	Apollo Server	Handles queries and mutations for core items like `WorkOrders`, `Invoices`, and `Contacts`.

REST Endpoints Diagram

The below diagram outlines every available REST API endpoint. Endpoint graph nodes have color-coded outlines indicating the level of authentication required for user access:

Endpoints outlined in yellow require authentication via auth token (for more info, see Fixit-API User Authentication)
Endpoints outlined in pink require both authentication and an active subscription (for more info, see Fixit SaaS Products)

flowchart LR
  root("/api") --> api("/api \n\n • GraphQL API entrypoint")
  root --> admin("/api/admin \n\n • CSP reports and \n healthchecks")
  root --> auth("/api/auth \n\n • User registration and logins \n (administers auth tokens)")
  root --> connect("/api/connect \n\n • Stripe Connect \n endpoints")
  root --> subs("/api/subscriptions \n\n • Endpoints for managing \n Fixit subscriptions")
  root --> webhooks("/api/webhooks \n\n • Webhook endpoints")
  subgraph gql ["ApolloServer GraphQL Endpoint"]
  api
  end
  subgraph express ["REST Endpoints"]
  admin --> csp("/api/admin/csp-violation \n\n • CSP #quot;report-to#quot;" target)
  admin --> healthcheck("/api/admin/healthcheck \n\n • Healthchecks target")
  auth --> register("/api/auth/register \n\n • User registration")
  auth --> login("/api/auth/login \n\n • User logins via Local\n or OAuth mechanisms")
  auth --> googleToken("/api/auth/google-token \n\n • User logins via Google\nOAuth2 OneTap FedCM")
  auth --> pwReset("/api/auth/password-reset \n\n • Password reset requests")
  auth --> token("/api/auth/token \n\n • Refreshes auth tokens")
  connect --> accountLink("/api/connect/account-link \n\n • Returns a link to the Stripe-hosted\nConnect onboarding portal")
  connect --> dashboardLink("/api/connect/dashboard-link \n\n • Returns a link to the Stripe-hosted\naccount management portal")
  subs --> promo("/api/subscriptions/check-promo-code \n\n • Validates user promo code inputs")
  subs --> pay("/api/subscriptions/submit-payment \n\n • Handles payments for \n Fixit subscriptions")
  subs --> portal("/api/subscriptions/customer-portal \n\n • Provides subscription \n management portal for users")
  webhooks --> whStripe("/api/webhooks/stripe \n\n • Stripe webhooks handler")
  webhooks --> whCustomer("/api/webhooks/* \n\n • Other webhooks")
  end

  classDef default fill:#1f2020,stroke:#7aa4c9,stroke-width:1px
  classDef authenticationRequired stroke:#f1ff2e
  classDef authAndSubscriptionRequired stroke:#ec4dbf,stroke-width:2px
  classDef subgraphArea fill:#474949,color:#e3e3e3

  class promo,token,pay,portal,accountLink,dashboardLink authenticationRequired
  class api authAndSubscriptionRequired
  class express,gql subgraphArea

GraphQL Schema

Check out the Fixit GraphQL Schema Explorer on Apollo Studio. There you'll find excellent tools for exploring the latest version of the Fixit GraphQL schema:

Documentation for all available objects, queries, mutations, and subscriptions.
An explorer for trying out operations with mock responses.
A comprehensive changelog for the schema SDL.

🔐 User Authentication

This API uses self-vended JSON Web Tokens to manage user authentication and authorization.

💎 Premium SaaS Products

The table below lists currently available Fixit SaaS products. Subscription management is powered by Stripe.

Product	Description	Price (USD)	Promo Code(s) Available?
Fixit SaaS Subscription	14-Day Free Trial	$0	N/A
Fixit SaaS Subscription	Monthly Subscription	$5/month	✓
Fixit SaaS Subscription	Annual Subscription	$50/year	✓

🗄️ DynamoDB Database

This API uses a single DynamoDB table with primary keys pk and sk, along with an overloaded data index attribute which supports a range of flexible queries using two GSIs: Overloaded_SK_GSI and Overloaded_Data_GSI.

Fixit-API Access Patterns

USERS
- Find a User by their email
- Find a User by their user ID
- Find a User by their phone
- Update a User's Subscription by sub ID
- Find a User's StripeConnectAccount by its ID
- Find a User's Subscription by its ID
- Find a User's Profile by its ID
CONTACTS
- Find a Contact by contact ID
- Find a User's Contacts using their user ID
INVOICES
- Find an Invoice by ID
- Find a User's Invoices using their user ID
- Find a User's Invoices by STATUS
- Find Invoices wihtin a given date range
WORK ORDERS
- Find a WorkOrder by ID
- Find a User's WorkOrders using their user ID
- Find WorkOrders within a given date range

Single Table Design

Item	`pk`	`sk`	`data`
User	USER#<timestampUUID>	#DATA#<userID>	<user_email>
User Subscription	<userID>	SUBSCRIPTION#<userID>#<timestamp>	<stripe_subscriptionID>
User Stripe Connect Account	<userID>	STRIPE_CONNECT_ACCOUNT#<userID>	<stripeConnectAccountID>
Work Order	<createdBy_userID>	WO#<createdBy_userID>#<timestamp>	<assignee_userID>
Invoice	<createdBy_userID>	INV#<createdBy_userID>#<timestamp>	<assignee_userID>
Contact	<userID>	CONTACT#<contact_userID>	<contact_userID>
Push Notification	<recipient_userID>	PUSH_RECEIPT#<userID>#<timestamp>	<pushReceiptID>

📦 CI/CD Pipeline

GitHub Actions

This project's CI/CD pipeline uses GitHub Actions to test, release, and deploy code changes.

Test - Runs test suites, adds test and coverage info to PRs, and updates CodeCov.
Release - Creates a new GitHub release using Semantic Release.
Deploy - Builds a Docker image, pushes it to Amazon ECR, and updates the ECS Task Definition and associated ECS Service.

Git Workflow

This project uses uses GitHub Flow to deploy two live environments - staging and production - both of which are associated with a Git branch for releases:

Environment	Release Branch	Permits `git push`
staging	next	✓
production	main	❌

Project versioning and the CHANGELOG.md are managed automatically via GitHub Actions and Semantic Release.

For more information on how new code is integrated and deployed, check out the guide to CONTRIBUTING.

Codegen

TypeScript types are generated using GraphQL Code Generator and the Fixit GraphQL schema. The same generated types are used throughout the entire Fixit stack.

When the Fixit GraphQL schema is updated during development, changes are automatically pushed to Apollo Studio, thereby enabling every component in the stack to use the latest version of the schema (or any particular previous version, if necessary). The schema changes are pulled into other Fixit repos using Rover GitHub Actions, but can also be pulled imperatively using the Rover CLI.