Stop Treating Forge Like a Backend, You’re Building It Wrong (Part 1: Scaling Patterns)

[#1]

I’ve been deep in Forge for a while now, and there’s a pattern I keep seeing.

People come into Forge thinking:

“This is just another backend.”

It’s not.

And if you build it like one, your app will break the moment it scales.

What Forge Actually Is

Forge is not Connect.
Forge is not your Node.js server.
Forge is not your AWS backend.

Forge is:

A serverless, event-driven runtime inside Atlassian’s ecosystem

That distinction matters.

You’re not hosting infrastructure.
You’re operating within constraints by design.

When building and thinking about UI, I recommend using custom UI (for any serious app) because it is predictable in change management and has room for architectural ceilings. An example of a production ready project structure

Recommended Project Structure 

forge-app/
│
├── manifest.yml # App definition (modules, permissions)
├── package.json # Backend dependencies
│
├── src/
│ ├── resolvers/ # Backend logic (functions)
│ │ ├── index.js # Main resolver entry
│ │ ├── scheduler.js # Scheduled jobs
│ │ ├── consumer.js # Queue processing
│ │ └── api.js # External API integrations
│ │
│ └── utils/ # Shared logic
│
├── static/
│ └── app/ # Custom UI (React)
│ ├── src/
│ ├── public/
│ └── build/
│
└── README.md

What You Can Do 

Let’s remove the noise and talk about reality.

1. Build Real Automation Systems

Not Jira Automation rules.

I’m talking about:

• Scheduled workflows
• Multi-step processing pipelines
• Cross-project orchestration

Using:

• scheduledTrigger
• queue
• consumer

This is how you build simple but get-the work done apps.

2. Integrate AI 

There’s a lot of noise around “Forge AI” but that's an EAP at the writing of this article

What you actually do:

• Call external APIs (OpenAI, etc.)
• Process results inside Forge

Simple, controlled, scalable. However, when ForgeLLM does go GA that would be a game changer.

3. Use Storage the Right Way

Forge gives you:

• KVS
• SQL 
• Object Store (EAP for now)

But here’s the mistake:

Forge storage is not your data warehouse.

Use it for:

• State
• Metadata
• Lightweight persistence

Your source of truth is still Jira/Confluence.

Where Most Apps Go Wrong

They ignore how Forge actually executes.

Everything is:

• Stateless
• Short-lived
• Event-driven

Yet people try to:

• Run long processes in one function
• Push large payloads
• Treat it like Express.js

That’s how you hit limits fast.

The Pattern That Actually Scales

If you’re building anything serious, this is the architecture:

+-------------------+
| Scheduled Trigger |
+-------------------+
          |
          v
+-------------------+
|   Push to Queue   |
+-------------------+
          |
          v
+-------------------+
|       Queue       |
+-------------------+
          |
          v
+-------------------+
|     Consumer      |
| (Async Processor) |
+-------------------+
          |
          v
+-------------------+
| External APIs /   |
| Forge Storage     |
+-------------------+

This is how Forge is meant to be used.

Critical Limitation 

Forge is not unlimited compute.

You must design around:

• Invocation limits
• Rate limits (Atlassian APIs + Forge runtime)
• Execution time limits
• Queue throughput limits

Queue Limits 

• Max 50 events per push batch
• Max ~200 KB per payload
• Designed for controlled async workloads

This is intentional:

Forge enforces limits to protect platform stability.

If ignored:

Your app will throttle, fail, or degrade under load.

The Mindset Shift

The biggest unlock in Forge is this:

Stop thinking “backend”
Start thinking “distributed functions”

Break your logic into:

• Small units
• Async workflows
• Queue-driven processing

Make everything:

• Idempotent
• Retry-safe
• Lightweight

I'm Not Done Yet

Forge is powerful, but only if you respect its model.

Most people don’t.

They fight the platform instead of designing with it.

And that’s the difference between:

• A demo app
• And a production-grade app used by thousands of teams

I’ll go deeper in my next article:

Part 2: Scaling Patterns

Because that’s where things get interesting.