SaaS backend · collaborative build

Most of the hard parts are other people’s APIs.

Co-developing a SaaS system whose core work is calling third-party services: authenticating, queueing, counting, publishing, and noticing when something goes wrong.

§ 1

The problem

A product that connects to other services inherits their failure modes. Tokens expire. Rate limits bite. Every call costs something, and a publishing job that fails in the middle of the night needs to fail somewhere a person will see it.

None of that is the feature a user asks for, and all of it decides whether the feature works. This case study is about that layer.

§ 2

Constraints

  • Services we don’t control. Third-party APIs have their own quotas, rate limits and changes.
  • Calls have a price. Avoidable calls are a cost, not just a performance problem.
  • Slow work can’t block a request. Publishing and other long-running work has to happen in the background.
  • Shared codebase. It’s a team build, so structure and visibility matter as much as cleverness.

§ 3

Approach

Coleroon.ai: high-level system sketchA web client talks to an API service. The API stores state in PostgreSQL, manages OAuth connections to third-party services, and enqueues work through Redis. Celery workers run background and publishing jobs and call third-party APIs. Every external call is recorded in a usage ledger of quota and cost, which the API checks before queueing more work. Observability spans all services, and everything runs in Docker containers.CONTAINERISED · DOCKERWeb clientReact · ViteAPI serviceauth · orchestrationRedisbroker · cacheCelery workersbackground + publishing jobsOAuth connectionsconsent · refreshUsage ledgerquota · costThird-party APIsrate limits · quotasPostgreSQLsystem of recordenqueuecallsrecord usageCHECKED BEFOREQUEUEING MORE WORKObservabilitylogs · job status · usage and cost, across API and workers

Scroll the diagram sideways →

Fig. · System sketchA simplified diagram drawn from the components I can name publicly. It is not the production architecture and leaves out providers, hostnames and internals on purpose.

OAuth connections are handled in one place, so consent and token refresh aren’t re-implemented per feature. Work that talks to third parties, publishing included, runs as background jobs: the API enqueues through Redis and Celery workers do the calling, retrying and reporting.

Usage is treated as data. Each external call is recorded against quota and cost, which turns “how much did that cost?” and “are we about to hit a limit?” into queries rather than guesses. Observability spans the API and the workers, so a failed job is visible, not merely logged. Docker keeps environments consistent across the team.

§ 4

What I did

I’m co-developer and technical lead on a collaborative build. The areas I worked on are the ones this page describes: OAuth third-party integrations, API orchestration, background jobs, quota and cost tracking, publishing workflows and observability.

It’s a team effort, so I’d rather name the areas I worked in than claim whole systems as mine.

§ 5

How it’s measured

For an integration-heavy system, the useful numbers are boring ones:

Calls per job
How many external calls a workflow needs, and how many are avoidable repeats.
Cost per workflow
What a unit of work costs in third-party usage.
Job health
Failure and retry rates for background and publishing jobs.

I’m not putting usage-reduction figures on this page yet. The ones I have come from testing, not production, and I’d want the method written up before quoting them.

§ 6

Status

This page deliberately says nothing about launch, users or revenue.

That’s for the team to state publicly, and there are no public screenshots or links here for the same reason. The diagram above is a simplified sketch, not the production architecture.

§ 7

What I learned, and what I’d do next

Make usage a first-class record. Once every external call is counted, cost and quota stop being surprises.

Background work needs a front door. A job queue is only half the design; the other half is being able to see what the queue did.

Next

  • Write up the usage measurements with their method, so they can be shared responsibly.
  • Publish a public product page or screenshots once the team approves them.