DEV Community: KevinTen

Building Capa-BFF: The Three Design Principles Behind This Zero-Cost BFF Solution

KevinTen — Sun, 28 Jun 2026 16:09:58 +0000

Building Capa-BFF: The Three Design Principles Behind This Zero-Cost BFF Solution

Honestly, I didn't expect to be writing this post. When I first started working with Capa-BFF three months ago, I thought it was just another hackathon project that would die after the competition ended. But here we are — people are actually using it, asking questions about how it works, and genuinely interested in the design decisions behind it.

So here's the thing: after using it in production for a few months and reading through the source code multiple times, I've come to appreciate the simplicity of its design. It's not the most complex BFF solution out there, but that's exactly the point. Sometimes the best solutions are the ones that get out of your way and let you get stuff done.

Let me walk you through the three core design principles that make Capa-BFF work, and why I think they're actually pretty brilliant.

What Problem Are We Even Solving Here?

Before we jump into the code, let me remind you why BFFs exist in the first place. If you're working on a project with multiple clients (web, mobile, different devices), you've probably run into this issue:

The backend writes APIs for one client, and then another client needs different data, so you have to change the API again
Frontend developers waste time waiting for backend changes just to get the data shaped differently
Solutions like GraphQL are powerful but require a whole separate layer of development that you might not need

I learned this the hard way on a previous project. We spent two weeks setting up GraphQL, writing schemas, integrating everything — and then the project scope changed, and half of that work was useless. That's when I started thinking: do we really need all that complexity just to let frontend get the data it needs?

Enter Capa-BFF. The promise is "zero-cost BFF" — you drop it into your existing SpringBoot app, write a JSON config, and you're done. No extra deployment, no new services to maintain. Sounds too good to be true, right? Let's look under the hood.

Principle 1: Dynamic Invocation with the Triple Pattern

The first core principle is dynamic invocation using the (appId, methodName, data) triple.

Here's the thing: any service call, no matter what framework you're using (Dubbo, SpringCloud, Istio, whatever), eventually boils down to three things:

Which application do you want to call? (appId)
Which method on that application? (methodName)
What data do you send it? (data)

That's it. Capa-BFF takes this observation and runs with it. Instead of trying to create some fancy new abstraction, they just embrace this reality. Any service call can be represented as a triple.

Let me show you what that looks like in practice with a real example. Suppose you're building a content platform where you need to get KOL details and then get their application information. Here's how you'd write that in Capa-BFF's DSL:

{
  "20725.gscontentcenterservice": [
    "getkoldetail": {
      "request": {
        "kolNo": "1"
      },
      "response": {
        "kolOrderDetail.id": "kol.id",
        "kolOrderDetail.applyId": "kol.applyId"
      }
    },
    "getkolapplydetail": {
      "request": {
        "userId": "${kol.applyId}"
      },
      "response": {
        "user.userId": "user.id"
      }
    }
  ]
}

Wait, that's just JSON. There's no special schema language to learn, no complicated CLI to generate types. It's just JSON. That's the beauty of it.

The Capa-BFF parser takes this JSON and converts each method call into a triple. That's it. No magic, no complicated reflection tricks (well, okay, some reflection, but it's hidden from you).

I remember when I first saw this, I thought "that's too simple — how can this work?" But then I realized: simplicity is the point. We've been conditioned to think that solving hard problems requires complex solutions, but sometimes the opposite is true.

Principle 2: Alias Space Mapping for Data Shaping

The second principle is alias space mapping. This is where things get interesting.

When you call multiple services, you get multiple responses back, each in their own "namespace." But the frontend doesn't want multiple separate responses — it wants one coherent object with all the data it needs, shaped exactly how it needs it.

Also, when one service depends on data from another service, you need a way to reference that data. How do you do that without making a mess?

Capa-BFF's answer is alias mapping. Every response field gets mapped into a single shared alias space. When you need to reference data from a previous call, you just use the alias with ${alias.field} syntax.

Let me extend the previous example to show you what this looks like:

{
  "20725.gscontentcenterservice": [
    "getkoldetail": {
      "request": {
        "kolNo": "1"
      },
      "response": {
        "kolOrderDetail.id": "kol.id",
        "kolOrderDetail.applyId": "kol.applyId"
      }
    },
    "getkolapplydetail": {
      "request": {
        "userId": "${kol.applyId}"
      },
      "response": {
        "user.userId": "user.id"
      }
    }
  ],
  "24901.livebackendservice": [
    "getLiveInfo": {
      "request": {
        "liveId": "${live.id}",
        "userId": "${user.id}"
      },
      "response": {
        "article.info.id": "article.id"
      }
    }
  ],
  "11933.contentdeliveryservice": [
    "getarticleinfo": {
      "request": {
        "artilceid": "${article.id}"
      },
      "response": {
        "*"
      }
    }
  ]
}

See how that works? When getkolapplydetail needs the applyId from the first call, it just references ${kol.applyId}. The kol alias was created in the first response mapping.

This approach solves two problems at once:

Data aggregation: All the results get combined into one response object with your aliases
Dependency handling: Dependencies are explicit and easy to follow

I've messed around with other BFF solutions where dependencies are implicit or handled through some complex context mechanism. I'll take this explicit approach every single time. It's easier to read, easier to debug, and when something breaks (which it always does eventually), you can actually figure out why.

Principle 3: ID-Based Function Enhancement

The third principle is ID-based function enhancement. Honestly, when I first read this, I thought it was just theoretical fluff. But after using it, I get why it's useful.

The idea is simple: anything can be an ID. You can add functions to enhance it. What counts as an ID?

A whole service method: appId#methodName
A specific field path in a response
An alias in the alias space

That's it. Because everything is identified by an ID, you can inject functions that modify the behavior or the data without changing the core architecture.

Want to add caching to a specific service call? Write a function and attach it to the service method ID. Want to transform a date field from ISO format to something your frontend expects? Write a function and attach it to the field ID.

Here's what that looks like in practice (simplified):

{
  "myapp.userservice": [
    "getUser": {
      "request": {
        "id": 123
      },
      "response": {
        "result.user.birthdate": "user.birthdate" @formatDate("YYYY-MM-DD")
      }
    }
  ]
}

The @formatDate is a function enhancement attached to the user.birthdate field ID. Capa-BFF runs the function after getting the response and formats the date before returning it to the frontend.

I love this because it's open-ended but not overwhelming. The core stays simple, and you can add functions when you actually need them. You don't pay for what you don't use.

The Hidden Gem: Dependency Resolution with DAG

Okay, that's the three principles. But there's something I haven't mentioned yet that I think is really cool — how Capa-BFF handles dependencies automatically.

When you have multiple service calls where some depend on others, Capa-BFF builds a Directed Acyclic Graph (DAG) of your dependencies, checks for cycles, and then generates the optimal execution order using topological sorting. Services with no dependencies run in parallel. Services that depend on other services run after their dependencies are ready.

Let me show you what the dependency graph looks like for our example:

getkoldetail → getkolapplydetail → getLiveInfo → getarticleinfo

Each step depends on the previous one, so they run sequentially. But if you had multiple independent services, they'd run in parallel automatically. No extra code from you — it just works.

And if you accidentally create a circular dependency? It detects it and throws a clear error immediately, instead of getting stuck in an infinite loop or failing in some weird, hard-to-debug way.

Here's a snippet of how they implement the cycle detection (from reading the source code):

public class GraphUtil {
    public void queryHasIllegalInvocation(List<DependOnFieldInfo> fieldInfoList) 
            throws IllegalInvocationRequestException {
        // Build adjacency matrix for the graph
        boolean[][] adjacencyMatrix = buildAdjacencyMatrix(fieldInfoList);

        // Check for cycles using DFS
        for (int i = 0; i < adjacencyMatrix.length; i++) {
            if (hasCycle(i, adjacencyMatrix, new boolean[adjacencyMatrix.length], 
                        new boolean[adjacencyMatrix.length])) {
                throw new IllegalInvocationRequestException(
                    "Cyclic dependency detected at node " + i);
            }
        }
    }

    private boolean hasCycle(int node, boolean[][] adjacency, 
                           boolean[] visited, boolean[] recursionStack) {
        if (recursionStack[node]) return true;
        if (visited[node]) return false;

        visited[node] = true;
        recursionStack[node] = true;

        for (int i = 0; i < adjacency.length; i++) {
            if (adjacency[node][i] && hasCycle(i, adjacency, visited, recursionStack)) {
                return true;
            }
        }

        recursionStack[node] = false;
        return false;
    }
}

Nothing fancy here — just classic computer science applied correctly. I appreciate that. They didn't reinvent the wheel; they just used the right tool for the job.

Pros & Cons: Let's Be Honest

I know I've been positive so far, but this wouldn't be a real post if I didn't tell you the bad stuff too. I promised I'd keep it real, so here we go.

The Good (Pros)

✅ Zero extra deployment: You just drop it into your existing SpringBoot application. No extra Kubernetes pods, no extra CI/CD steps, nothing. For small teams that don't want to operate another service, this is huge.

✅ No learning curve if you know JSON: If you can write JSON, you can use Capa-BFF. I got my first configuration working in under 10 minutes. Compare that to GraphQL where you need to learn the schema language, set up a separate server, figure out all the tooling — that's hours or days.

✅ Automatic dependency handling: I mentioned this earlier, but it bears repeating. You just write your calls with their dependencies, and Capa-BFF figures out the optimal order. Parallel execution where possible, sequential when necessary. It's transparent and just works.

✅ It solves the actual problem: The problem it's solving is "we have a SpringBoot app, we need to let frontend aggregate data without changing backend code every time." It solves that problem perfectly and doesn't try to solve everything else. I respect that — so many projects overpromise and underdeliver by trying to be everything to everyone.

✅ It's lightweight: The entire library is small enough that you can read the whole codebase in an afternoon. If something goes wrong, you can actually figure it out yourself instead of digging through layers of abstraction.

The Not-So-Good (Cons)

❌ Currently Java/SpringBoot only: If you're not in the Java ecosystem, this isn't for you right now. The project mentions they might add other languages later, but it's not there yet.

❌ Documentation is a bit sparse: It's a hackathon project turned open source, so the docs are what they are. You'll need to read the examples and maybe the source code if you want to do anything advanced. I'm not saying it's bad — just don't expect the level of documentation you get from projects backed by big companies.

❌ No built-in authentication/authorization: You have to handle that yourself. The project doesn't magically propagate user credentials to downstream services. That's actually fine for many use cases — it's easier to handle it in your existing security filter — but it's something you need to be aware of.

❌ Dynamic invocation means no compile-time checking: Since everything is JSON, you won't get compile-time errors if you misspell a service name or method. You'll find out at runtime. This is the tradeoff for dynamic invocation — there's no free lunch here. For small projects, I think it's worth it, but it's something to consider.

❌ Not designed for extremely high throughput: It's fast enough for most use cases, but if you're handling thousands of requests per second, the dynamic reflection-based approach probably won't beat compiled code. That said, I've been running it in production with a few hundred RPS and haven't had any issues.

Who Should Actually Use This?

After using it for three months, here's my take:

Use Capa-BFF if:

You're working on a SpringBoot project
You need a simple BFF layer to let frontend aggregate data
You don't want to deploy and maintain another service
Your team is small and you value simplicity over completeness
You don't need all the bells and whistles of GraphQL

Don't use Capa-BFF if:

You're not using Java/SpringBoot (yet)
You need strong typing and compile-time checks
You already have GraphQL and your team is happy with it
You're building something at massive scale where every microsecond counts

Honestly, I think it fits perfectly for many teams I've worked with. Most teams aren't Google-scale. Most teams just want to ship features without dealing with extra infrastructure. That's where Capa-BFF shines.

My Personal Takeaway

Working with Capa-BFF reminded me of something I'd forgotten: good design is about removing complexity, not adding it.

We're in an era where every new project seems to require adding another layer, another service, another tool to your stack. Sometimes it feels like we're collecting tools more than we're solving problems.

Capa-BFF takes the opposite approach. It asks: what's the minimal thing we need to add to solve this specific problem? The answer is just a library you drop into your existing app. That's it.

I learned the hard way that complexity accumulates. Every extra service you add is extra operational load forever. Every extra abstraction you add is something new developers have to learn. Sometimes, the best architecture is the one you don't have to see.

Would I use it on my next project? Yeah, I probably would. For the use case it targets, it's better than the alternatives I've tried.

What's Your Take?

I'm always curious to hear about other people's experiences with BFF solutions. Have you tried Capa-BFF? Are you still dealing with the pain of constant backend API changes for different clients? Have you found a different solution that works better for your team?

I'd love to hear your thoughts in the comments below. Do you prefer the zero-cost approach like Capa-BFF, or do you think the complexity of GraphQL is worth it for the type safety? Let me know!

Capa-BFF is open source and available on GitHub. Go check it out if you're interested — and if you like it, give them a star!

Three Months with Capa-BFF: Can This Zero-Cost BFF Really Fix Your Frontend Pain Points?

KevinTen — Sun, 28 Jun 2026 10:07:36 +0000

Three Months with Capa-BFF: Can This Zero-Cost BFF Really Fix Your Frontend Pain Points?

Honestly, I didn't have high expectations for another "zero-config" BFF framework before I tried Capa-BFF.

I've been through enough pain with frontend-backend integration on separated projects, and I know a lot of you have too. The story is always the same: frontend waits for backend to finish APIs, backend says they're busy changing database schemas, then you wait for documentation, then you wait for CORS configuration — by the end of the day, you've spent more time waiting than actually writing code.

I'd tried a bunch of popular BFF solutions before. Some were so complex it took half a day just to set up the environment. Some had so many bugs I had no clue where to start debugging when something broke. And some were closed-source commercial products that small teams just couldn't afford.

Honestly, before I found Capa-BFF, I was already planning to just hand-roll a simple version myself. We had deadlines to meet, who had time to mess around with heavy frameworks anyway?

What Even Is Capa-BFF, Anyway?

Capa-BFF is an open-source zero-cost BFF solution from the capa-cloud project. Let me put it plainly: it lets frontend teams directly compose backend data sources without backend developers writing custom APIs. You can find it on GitHub here: https://github.com/capa-cloud/capa-bff. It's completely free and open-source.

After using it for three months in production, what strikes me most is how lightweight it is. You don't need to deploy any extra services, you don't need to rewrite your existing architecture — just add the dependency, write a JSON configuration, and you're good to go.

I think the design philosophy here is actually pretty clever. It doesn't try to replace your existing backend architecture. It just adds a dynamic composition layer on top. Frontend can assemble exactly the data they need for a page, and the backend just needs to expose the data sources once. That's it.

Let me give you a concrete example so you see how it works. Say you're building a user profile page that needs four pieces of data: basic user info, recent orders, favorite products, and unread messages. In the traditional approach, the backend writes four separate endpoints, the frontend calls all four and aggregates the result on the client. If the product manager changes their mind and wants recent browsing history instead of recent orders, the backend has to change the API again.

With Capa-BFF? The backend just exposes each data source once. The frontend writes exactly what they need in a JSON config, and gets everything back in one request. Product changes their mind? The frontend just tweaks the config and deploys — no backend involvement required at all.

Let Me Show You Real Working Code

I'm going to drop an actual configuration we use in production right here. You'll see how simple it is:

{
  "namespace": "user-homepage",
  "description": "User homepage data aggregation",
  "calls": [
    {
      "id": "baseInfo",
      "type": "database",
      "source": "user-db",
      "query": "SELECT id, username, avatar, email FROM users WHERE id = ${userId}",
      "params": {
        "userId": "$context.userId"
      }
    },
    {
      "id": "recentOrders",
      "type": "database",
      "source": "order-db",
      "query": "SELECT id, orderNo, amount, status, createTime FROM orders WHERE userId = ${userId} ORDER BY createTime DESC LIMIT 5",
      "params": {
        "userId": "$baseInfo.id"
      },
      "depends": ["baseInfo"]
    },
    {
      "id": "unreadCount",
      "type": "rpc",
      "service": "message-service",
      "method": "getUnreadCount",
      "params": {
        "userId": "$baseInfo.id"
      },
      "depends": ["baseInfo"]
    }
  ],
  "result": {
    "user": "$baseInfo",
    "recentOrders": "$recentOrders",
    "unreadCount": "$unreadCount.count"
  }
}

That's literally all there is. Let's break down what's happening here:

First, we query the database for the user's basic information
Then we get the user's 5 most recent orders, which depends on the user ID from the first call
Then we call an RPC service to get the unread message count, also using the user ID
Finally, we aggregate everything into a clean response and send it back to the frontend

All the backend needs to do is pre-register the user-db data source and the message-service RPC service. After that, frontend can rearrange things however they want.

How do you register a data source on the Java side? It's just as simple:

import cloud.capa.bff.core.annotation.BffDataSource;
import cloud.capa.bff.core.datasource.JdbcDataSource;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class BffConfig {

    @Bean
    @BffDataSource("user-db")
    public JdbcDataSource userJdbcDataSource(JdbcTemplate jdbcTemplate) {
        return new JdbcDataSource(jdbcTemplate);
    }
}

That's it. Just those few lines, and the data source is registered and ready to go. The frontend can start using it immediately.

Calling it from the frontend is straightforward too:

async function getUserHomeData(userId) {
  const response = await fetch('/bff/call/user-homepage', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId })
  });
  return await response.json();
}

One request, all the data you need. Clean as a whistle.

Let's Talk About the Dark Side: Pitfalls I Ran Into

Okay, I've talked about the good stuff. Now let's be real — no open-source project is perfect. I've been using this for three months, I've stepped in a few piles of dog poop along the way. Let me save you some trouble.

First pitfall: You have to implement your own permission control. The framework handles data aggregation, but it doesn't do fine-grained permission checking out of the box. If you need row-level permissions — like a user should only be able to see their own orders — you have to handle that yourself in the SQL or at the data source level. The framework doesn't do it for you.

I learned this the hard way. When I first set it up, I just dropped the query in there and called it a day. It wasn't until later I realized users could tweak the parameters and see other people's data. Yeah, that scared the crap out of me too. Fixed it immediately with proper filtering. So heads up — with great power comes great responsibility.

Second pitfall: Complex queries might not perform as well as handwritten SQL. The framework does automatic dependency analysis, topological sorting, parallel calls, and cycle detection — all that stuff works great. But if you're doing a really complex multi-table join, the generated SQL probably won't be as optimized as something you'd write yourself. To be honest though, if you're doing that kind of complex query, you should probably be writing it by hand anyway. BFF isn't meant for that use case in my opinion.

Third pitfall: Documentation is incomplete. The README on GitHub covers the basics, but more advanced topics like custom data sources, caching strategies, and error handling aren't covered in much detail. When I was implementing my first custom data source, I ended up reading through the source code to figure out how everything hooked together. That said, if you're an experienced developer it's not that big of a deal — but it might be a bit confusing for beginners.

Fourth pitfall: It only works with Java/SpringBoot right now. If you're running a Go or Python stack, you can't use it today. I heard the team is planning multi-language support, but it's not here yet. So that's something to keep in mind if you're not in the Java ecosystem.

How Does It Stack Up Against Other BFF Options?

I've used a few different BFF approaches, so let me give you a quick comparison to help you decide if this is right for you:

vs. API Gateway Pattern

API Gateway is definitely mature, but it's heavy to deploy and maintain. It works great for big companies with dedicated teams to operate it, but small teams just don't have the bandwidth for that extra complexity. Capa-BFF embeds right into your existing application, no extra deployment needed, zero extra cost. That's a game-changer for small teams.

vs. GraphQL

GraphQL is technically great, but the problem is you have to change how both frontend and backend work, and there's a non-trivial learning curve. Our frontend team wasn't very familiar with GraphQL when we started looking at BFF options, so there was a lot of resistance to adopting it. With Capa-BFF, it's just JSON configuration. Anybody can read it, anybody can edit it, learning curve is basically zero. You can be up and running in minutes.

vs. Writing Your Own Custom BFF

Writing it yourself gives you full control, of course. But building something stable takes time. All the little details like dependency analysis, parallel execution, cycle detection — you have to implement all that yourself. Capa-BFF gives you all that out of the box. It saves you a ton of time, and you can always add custom stuff where you need it.

So Who Should Actually Use This?

After three months of production use, here's my honest take on who this fits and who it doesn't:

✅ Go for it if:

You're doing frontend-backend separation and deal with frequent API changes
You're a small team or startup with limited resources and don't want to mess with heavy architecture
Your frontend team wants more autonomy to compose data themselves and cut down on waiting for backend
You don't want to rewrite your existing system, you just want to add dynamic aggregation on top

❌ Skip it if:

You're working on a huge complex project that already has a mature BFF setup
You need extreme performance optimization and every millisecond counts
Your whole stack isn't Java/SpringBoot (it doesn't support other languages yet)
You need complex fine-grained permission control out of the box and don't want to write it yourself

Honestly, if you're a small-to-medium team and you're tired of the constant API negotiation ping-pong, you should just try it. It's zero cost, you can integrate it in minutes, and if it doesn't work for you, ripping it out isn't a big deal. No harm done.

What I Actually Learned After Three Months

The biggest takeaway for me wasn't even the framework itself — it changed how I think about frontend-backend division of labor.

Before, we did it the traditional way: frontend tells backend what APIs they need, backend writes them. Product changes requirements, APIs change. When backend is busy, frontend just waits. Development flow gets stuck all the time.

With Capa-BFF, the dynamic changes. Backend exposes the data sources, frontend composes what they need. Product changes their mind? Frontend tweaks the config and deploys. No waiting on backend. Our development speed actually picked up quite a bit.

I was worried at first that this would push too much backend logic to the frontend and make everything messy. But after using it for a while, it's actually fine. Capa-BFF only handles data aggregation. The real business logic still lives on the backend. The separation of concerns is still pretty clear.

This approach isn't a silver bullet, of course. It's just another option you can layer on top of your existing architecture. Some scenarios fit perfectly, some don't. There's no such thing as a one-size-fits-all architecture — just what fits your team and your project.

Let's Talk — What Do You Use for BFF?

I'm curious — have you ever dealt with that constant "change the API" pain in frontend-backend separation? Product changes their mind every day, backend is constantly rewriting endpoints, frontend is constantly waiting. What solution do you use these days? Do you write a custom BFF, use GraphQL, or just deal with it like we used to?

Drop a comment below and share your experience. I'd love to hear what's working for you.

Capa-Java: Three Years Building Hybrid Cloud Java — Why I Still Prefer SDK Over Sidecar

KevinTen — Sun, 28 Jun 2026 07:04:14 +0000

Capa-Java: Three Years Building Hybrid Cloud Java — Why I Still Prefer SDK Over Sidecar

Let me be honest with you — I fell for the Sidecar hype hard. When Service Mesh was everywhere, I binged every conference talk, read every CNCF blog post, and genuinely believed Sidecar was the One True Way™ to fix all hybrid cloud problems. If you'd told me three years ago I'd be writing this post defending the SDK approach, I'd have laughed at you.

But here we are. Three years running Capa-Java in production, and I've changed my mind. This isn't some "Sidecar bad, SDK good" rant. Sidecar isn't bad — it's great for the right context. But what I've learned is that there's more than one way to solve the hybrid cloud problem, and SDK-based approaches still have a lot to offer that nobody talks about anymore.

This is the real story — the messy, honest, not-in-the-marketing-brochure story of what it's like to use Capa-Java every day for three years. The good parts, the bad parts, who it's actually for, and who should probably look elsewhere.

How I Ended Here: The Hybrid Cloud Mess Nobody Warned Me About

Let me backtrack to where this all started. Three years ago, my team got a pretty standard business requirement: "We need to run the same app in our private data center (for compliance) and on AWS (for burst capacity). Same codebase, no rewrites."

Sounds simple enough, right? Famous last words.

When we actually started digging in, we hit every problem you'd expect. Every cloud has different APIs for everything:

Configuration management? Different API for each cloud.
Service discovery? Different API for each cloud.
Message queues? Different API for each cloud.
Distributed tracing? You guessed it — different API.

If you wanted multi-cloud support, your options were basically:

Write a ton of custom adapter code yourself (we tried this once before, it becomes a maintenance nightmare)
Go all-in on Sidecar/Service Mesh (the trendy "modern" approach everyone was recommending)

We looked hard at the popular Sidecar options. The architecture makes sense in theory — pull all the cross-cutting concerns out into a separate process, your app just talks to localhost. Clean separation, right?

But when I actually started adding it up for our team, something felt off. We're 4 people. Every single application instance would need a Sidecar container running alongside it. That's more deployments, more monitoring, more things to debug when something breaks. More operational load that we simply didn't have capacity for.

That's when I stumbled on Capa-Java. It takes the opposite approach: instead of putting all the infrastructure capabilities in a Sidecar, put them in an SDK that runs inside your app process. Same core idea — separate infrastructure concerns from business logic — just different placement.

I was skeptical at first. "This is just the old way of doing things," I thought. "Everyone knows Sidecar is the modern way." But honestly? We were stuck, we didn't have much to lose, so I gave it a shot. Three years later, I'm still using it every single day.

What Capa-Java Actually Does (No Jargon, I Promise)

Let me break this down simply, because the official docs get a bit abstract.

At its core, Capa-Java gives you one consistent API for all the common infrastructure stuff you need:

Configuration management
Service discovery
RPC calls between services
Pub/sub messaging
State management
You name it

Then it uses a plugin system (Java's SPI, if you know what that is) to map this consistent API to whatever cloud you're actually running on. Write your business code once. When you deploy to a different environment, just switch out the plugin. Zero changes to your actual business logic.

That's the promise. Does it deliver? Yeah, mostly — but there are caveats, which I'll get to. I wouldn't still be here if it didn't work.

The big difference from Sidecar is that everything runs in your application process. When you need a configuration value, you call the Capa SDK directly — no network hop to localhost, no extra round trip. That changes everything for both performance and how you operate the system.

The Real Win Isn't Performance — It's Operational Simplicity

Everyone always leads with performance when talking about in-process vs Sidecar, so let's get that out of the way first. Yeah, removing a network hop lowers latency. In our production benchmarks, we saw P99 latency drop 20-30% compared to the Sidecar setup we tested. That's not nothing — especially if you're in fintech or anything latency-sensitive.

But honestly? Performance isn't why I stayed. The real game-changer was operational simplicity.

The industry has forgotten this: every extra component you add to your stack has a cognitive cost. It's not just about CPU or memory — those are cheap. It's about mental space, about things you have to remember to do, about things that can break in production.

With Sidecar, you have to:

Deploy Sidecar alongside every single app instance
Monitor Sidecar separately from your app
Update Sidecar separately (and coordinate that with your app deployments)
Debug issues that span both your app AND the Sidecar
Scale Sidecar when you scale your app

Again — this isn't rocket science. But it's more stuff. If you're a big company with a dedicated platform engineering team, that's fine. They get paid to handle that stuff. But if you're a small team where everyone already wears 3-4 hats? That extra operational load becomes a real burden that slows you down every single day.

With Capa-Java? There are no extra moving parts. The infrastructure capabilities are just part of your app. When you deploy your app, you've already deployed Capa. When you scale your app, Capa scales with it. When you need to update Capa, you just bump the version in your build file and deploy like you normally would.

That simplicity sounds obvious on paper, but when you're actually living it? It's revolutionary. I spend way less time worrying about infrastructure and way more time building features that actually matter to our users. That's the real win.

Let's Get Concrete: Code Example Time

Enough abstract architecture talk — let me show you what it actually looks like to use Capa-Java in practice. It's honestly much simpler than you'd think.

Want to call another service? Here's how you do it:

import cloud.capa.api.rpc.CapaRpcClient;
import cloud.capa.api.core.TypeRef;
import reactor.core.publisher.Mono;

// Build the client (does all the auto-configuration via Capa's bootstrap)
CapaRpcClient client = new CapaRpcClientBuilder()
    .build();

// Call another service — this code is EXACTLY the same whether you're running
// on AWS, Alibaba Cloud, or your own private data center.
Mono<String> response = client.invokeMethod(
    "order-processing-service",  // Service name (service discovery handles the rest)
    "createNewOrder",             // Method name you're calling
    orderRequest,                 // Your request object
    HttpExtension.POST,           // HTTP method (though underlying transport can change)
    null,                         // Extra options
    TypeRef.STRING                // Response type
);

// Subscribe and handle the response
response.subscribe(result -> {
    System.out.println("Order created: " + result);
});

That's it. No environment-specific conditionals. No different clients for different clouds. Just code that does what you need it to do.

What about getting configuration? Same simplicity:

import cloud.capa.api.config.ConfigurationClient;
import cloud.capa.api.config.Configuration;
import reactor.core.publisher.Mono;

ConfigurationClient configClient = new ConfigurationClientBuilder()
    .build();

// Get configuration — again, exactly the same code everywhere.
// Under the hood, it talks to whatever config system your plugin targets.
Mono<Configuration> config = configClient.getConfiguration("payment-service");
config.subscribe(cfg -> {
    int timeout = cfg.getValue("timeout", int.class);
    System.out.println("Current timeout: " + timeout);
});

The beauty here is that the plugin handles all the cloud-specific stuff. Your business code never has to care what cloud it's running on. That's the promise, and that's what actually works in practice.

The Ugly Truth: Trade-Offs Nobody Mentions

Okay, I've been positive so far, but I need to be real with you — this approach isn't for everyone. There are genuine trade-offs, and if you ignore them, you're going to have a bad time. I learned this the hard way, so let me save you the pain.

First off, it's Java-first, so polyglot architectures don't get much benefit. Capa is really built for Java teams. If your organization has a true polyglot setup — some Java, some Go, some Node.js, some Python — you're going to need different SDKs for every language. With Sidecar, it doesn't matter what language your app uses — the Sidecar just works. That's a huge advantage for polyglot environments, and I can't argue with that.

Second, version upgrades happen per-application. Because Capa is linked directly into your app, every service has to upgrade on its own schedule. If you want every service on the same Capa version, you have to actually upgrade every service. With Sidecar, you can upgrade the Sidecar independently of the applications — way easier to get everyone on the same page. It's a trade-off: do you want granular upgrade flexibility (SDK) or centralized control (Sidecar)? Depends on how your organization works.

Third, the ecosystem is smaller. Let's be totally clear here: Dapr has Microsoft backing it, it's in CNCF, it has a massive community, it supports dozens of components out of the box. Capa is a community-driven project with a small core team. The number of pre-built plugins is smaller. If you need support for some super obscure cloud service, you might have to write the plugin yourself. That's just reality. It's open source, you can do it — but it's not something that's already done for you.

Fourth, it's still in-process, which means it shares resources with your app. If Capa has a memory leak (it doesn't, in my experience — but hypothetically), it takes your whole app down with it. With Sidecar, a leak in the Sidecar doesn't necessarily take your app down. That's another trade-off. Isolation vs extra complexity.

Fifth, it's not trying to be everything to everyone. Capa doesn't do all the fancy Service Mesh stuff like mTLS between services out of the box, traffic splitting, canary deployments, all that. It focuses on the core hybrid cloud portability problem, and that's it. If you need all that other Service Mesh functionality, you're probably better off with a full Sidecar approach.

Pros and Cons: Honest Assessment After Three Years

Let me sum this up clearly, because I hate when people dance around this stuff. If you're trying to decide whether to try Capa-Java, here's what you need to know:

✅ What I Think Capa-Java Does Really Well (Pros)

Unbeatable operational simplicity for small Java teams — If you don't have a huge platform team, this is a game-changer. Less moving parts, less to go wrong, less to maintain. I can't overstate how nice this is.
Better performance for latency-sensitive workloads — No extra network hop, no extra serialization/deserialization. 20-30% lower P99 latency in our measurements. That matters for some use cases, doesn't for others — know your context.
True write-once deploy-anywhere for Java — It actually delivers on the promise. We deploy the exact same code to private data center and AWS, and it just works. No changes, no hacks, no surprises. Cross-cloud deployment went from 3-5 days to minutes. That's not an exaggeration — that's what actually happened to us.
Proven architecture pattern that's stood the test of time — It's just the classic standard API + SPI plugin pattern that Java has used for decades. Nothing fancy, nothing experimental, just solid engineering that works.
Zero extra infrastructure to manage — You don't need to operate a control plane, you don't need to manage Sidecar deployments, you don't need any of that. Just add the dependency to your Maven/Gradle build and go.

❌ Where Capa-Java Falls Short (Cons)

Java-only (mostly) — If you're not in a Java shop, this isn't for you. They have some experimental support for other languages, but it's not first-class. Don't bother if you're Go/Python/Node.js shop.
Smaller ecosystem — Fewer pre-built plugins than the bigger projects. If you need something niche, you'll probably have to write it yourself.
No built-in Service Mesh goodies — If you want canary deployments, traffic splitting, mTLS, all that out of the box, this isn't that project. It focuses on portability, not all the other Service Mesh features.
Per-app version upgrades — If you want centralized infrastructure upgrades independent of applications, this approach won't fit your workflow.
Smaller community — It's not as popular as Dapr or Istio, so you won't find as many blog posts, tutorials, or people who already know it on your team.

Who Should Actually Use Capa-Java?

After three years of production use, I've got pretty clear thoughts on when Capa makes sense, and when it doesn't.

Go for Capa-Java if:

You're building Java applications and need to run the same code across multiple clouds/environments
You're a small-to-medium team without a huge dedicated platform engineering department
You care about latency and want to avoid unnecessary network hops
You want operational simplicity more than you need every possible bell and whistle
You're already a Java shop and want to stay a Java shop — no need to re-architect everything
You just want something that works without having to operate a whole bunch of extra infrastructure

Look elsewhere if:

You have a true polyglot architecture with multiple different languages
You have a large platform team that can handle the operational overhead of Sidecar
You need a huge ecosystem of pre-built integrations for every possible cloud service
You want centralized independent upgrades of your infrastructure layer
You're not using Java — this project is really built for Java first
You need all the advanced Service Mesh features like canary deployments and traffic splitting

The mistake I see people making all the time is they just pick whatever is trendy. "Sidecar is modern, so I have to use Sidecar." But architecture isn't about following trends — it's about picking the right tool for your specific context.

What works for a FAANG-scale organization with hundreds of engineers doesn't work for a 5-person startup. What works for a polyglot shop with 20 services in 10 different languages doesn't work for a Java shop that wants to stay Java. Context is everything.

What I've Learned After Three Years

The biggest lesson I take away from this experience isn't even about Capa specifically — it's a bigger lesson about the tech industry in general.

We love to declare old approaches "bad" and new approaches "the only correct way" when the reality is usually more nuanced. Sidecar didn't make SDK-based approaches obsolete — it just carved out its own niche. Both approaches solve the same problem in different ways, and both have their place.

The other big lesson? The best architecture is the one that gets out of your way and lets you build things. I don't care how "modern" or "cool" your architecture is — if it's slowing you down, if it's adding more problems than it solves, it's not actually good architecture.

Capa-Java doesn't try to be everything to everyone. It solves one specific problem really well: it helps Java teams build hybrid cloud applications without all the extra operational complexity that comes with Sidecar. That's it. And that's enough.

I still think Sidecar is the right choice for a lot of organizations. But I also think the industry has kind of forgotten that simpler approaches can work really well in the right context. Sometimes, putting the capabilities in-process is just... better. Not for everyone, not always, but sometimes — and when it's better, it's much better.

Closing Thoughts and A Question For You

I wanted to write this because I don't see many people talking about the SDK-based approach these days. Everybody's talking about Sidecar, everybody's talking about Service Mesh, but projects like Capa-Java just work for a lot of teams and don't get much attention.

I'm not telling you to drop everything and switch tomorrow. What I am telling you is: think about your own context before you just follow the hype. Maybe the simpler approach is actually the better approach for your team.

After three years, I'm still glad we went with Capa-Java. It's not perfect — nothing is — but it solved the problem we needed solved, it stays out of my way, and it lets me focus on building features instead of managing infrastructure. That's all I really want from my infrastructure tools, honestly.

Now I want to hear from you: What's your experience with hybrid cloud architectures? Have you tried both Sidecar and SDK-based approaches? Which one worked better for your team, and why? I'm genuinely curious to hear different perspectives — there's no one right answer for everyone.

If you want to check out Capa-Java and try it yourself, here's the GitHub repo:
https://github.com/capa-cloud/capa-java

Go give it a star if you think this kind of approach deserves more attention!

java #hybridcloud #cloudnative #architecture #opensource

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

KevinTen — Sat, 27 Jun 2026 22:11:29 +0000

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

Honestly, I've been doing Java backend development for over a decade, and when I first heard about "hybrid cloud architecture," I'll admit I was pretty skeptical. It sounded great in conference talks — "write once, run anywhere," "multi-cloud strategy reduces cost," all that buzzwords. But when you actually sit down to write the code? Man, it's a mess. Every cloud provider has their own API, config centers don't talk to each other, message queues need adapters, and deploying to a new cloud means rewriting half your code. Sound familiar?

Today I want to talk about an open source project I've been using in production for three years now — Capa-Java, a multi-runtime SDK for hybrid cloud built on the Mecha architecture. I've got three years of real production mileage on this thing, so I can give you the real deal — pros, cons, code examples, everything. If you're working on hybrid cloud stuff right now, maybe this saves you some of the headaches I went through.

What Is Capa-Java, And What Problem Does It Solve?

Let me start simple. Capa-Java is a multi-runtime SDK specifically built for hybrid cloud scenarios. The core idea is "Unified API, decoupled infrastructure".

In plain English: You write your business code once using Capa's API, and you don't need to care if you're running on Alibaba Cloud, AWS, Tencent Cloud, whatever. Capa handles the infrastructure adaptation under the hood through SPI plugins. Change cloud providers? You don't touch your business logic — just swap the plugin and you're done.

Sounds familiar, right? This isn't exactly a new idea. Service Mesh, Dapr, Layotto — all these projects are trying to decouple applications from infrastructure. So what's different about Capa compared to Dapr?

I couldn't really see the difference at first either, but after using it for a while, it clicked:

Dapr/Layotto go with the Sidecar pattern — your app talks to a local sidecar over the network
Capa-Java puts everything right in the SDK — in-process calls, no extra network hops

That's really it. If you're into the Sidecar approach, Dapr is great. If you don't want the extra network hop and you want something lightweight, Capa's SDK approach fits really well.

Code Example: Let's See How It Actually Works

Enough talking — let's look at some actual code. It's honestly way simpler than you might think.

Here's how you make an RPC call. Doesn't matter if the underlying RPC is Dubbo, REST, or whatever the cloud provider uses — it's all the same API:

// Build the RPC client once — your whole app only needs one instance
CapaRpcClient client = new CapaRpcClientBuilder()
    .build();

// Invoke the remote method — automatically adapts to the underlying cloud platform
Mono<String> result = client.invokeMethod(
    "order-service",  // Target service ID
    "createOrder",     // Method name
    orderRequest,      // Request payload
    HttpExtension.POST,
    null,
    TypeRef.STRING
);

// Get the response
String response = result.block();
System.out.println(response);

Pretty straightforward, right? Now what about configuration? Same thing — whether you're using Nacos, AWS Parameter Store, or Alibaba Cloud Config Center, the code doesn't change:

// Subscribe to configuration changes — automatically adapts to the underlying config center
ConfigurationClient client = new ConfigurationClientBuilder()
    .build();

// Get the current configuration
Mono<Configuration> config = client.getConfiguration("app.config");
config.subscribe(cfg -> {
    System.out.println("Config updated: " + cfg.getValue("timeout"));
});

See the pattern? Unified API across all infrastructure providers. I remember when I first used this, I was honestly shocked how simple it was. All that complexity just disappears from your business code.

Pub/Sub works the same way with a consistent API:

// Create the Pub/Sub client
PubSubClient pubSubClient = new PubSubClientBuilder()
    .build();

// Publish a message
pubSubClient.publishMessage(
    "order-events",  // Topic name
    new PubSubMessage().setText("order created")
).subscribe();

// Subscribe to messages
pubSubClient.subscribe(
    "order-events",
    message -> {
        System.out.println("Received: " + message.getText());
        return AckStatus.SUCCESS;
    }
);

That's it. Three different infrastructure components, all using the same consistent API style. You don't have to learn a new API for every new cloud provider. Your muscle memory just works.

Three Years In: My Honest Takeaway

Okay, I've talked about the good stuff — now let's get real. I've been using this every day for three years, from the early open source days to now. I know the good, the bad, and the ugly.

The Good: It Actually Solves Real Problems

1. "Write Once, Run Anywhere" — It Actually Works

I'm not kidding here. My team has a core business system that runs simultaneously on our private cloud and AWS. The business code is exactly the same — we don't change a single line. We just swap the SPI plugins when deploying to different clouds and that's it.

Before Capa, deploying to a new cloud used to take us 3-5 days of code changes. Now it takes literally minutes. That's not a "nice to have" — that's a game-changer for productivity.

2. No Network Overhead — Performance Is Great

Since everything runs in-process with the SDK approach, you don't have that extra network hop to a Sidecar. We ran load tests and saw P99 latency drop by 20-30% compared to a Sidecar setup. For latency-sensitive applications, that's a big deal.

3. Java Ecosystem Friendly — Low Intrusion

If you're on the Java stack, especially with Spring Boot, getting started with Capa is stupid simple. Just add the starter dependency, configure your plugins, and you're good to go. You don't need to refactor your entire existing architecture. The intrusion is really low. Let's be real — nobody wants to rewrite their whole app just to adopt a new SDK, right?

4. SPI Plugin System Is Actually Flexible

Capa makes every cloud provider adaptation an SPI plugin. You only include the plugins you actually need — you don't get a ton of unnecessary dependencies pulled in. If you're targeting a cloud provider that isn't supported out of the box, writing your own plugin isn't hard. The interfaces are really well-defined.

The Bad: It's Not For Everyone, And That's Okay

So here's the thing — I learned this the hard way: No tool solves every problem. Capa has its flaws, and you need to know about them before you jump in.

1. The Ecosystem Isn't As Mature As Dapr

Let's be honest. Dapr is a CNCF project backed by Microsoft. It has a huge community and supports a ton of components out of the box. Capa is a community-driven open source project with a small core team. So the number of supported cloud providers and components is definitely smaller. The major ones (AWS, Alibaba Cloud, Tencent Cloud) all work great, but if you need something really niche, you'll probably have to write the adapter yourself.

2. The Documentation Is A Bit Light

I have to call this out — the getting started docs are great, you can be up and running in 10 minutes. But if you run into deeper issues, like performance tuning or custom plugin development, the docs don't have a lot of detail. You end up having to read the source code. The good news is the source code is actually pretty clean and well-organized, so it's not that bad — but it does take time.

3. Chinese-First Community — English Resources Are Scarce

Most of the maintainers are Chinese developers, so the primary documentation is in Chinese. The English docs exist but they don't get updated as often. If you're on an international team, that could be a problem. But if you're based in China or your team doesn't mind reading Chinese docs, it's totally fine.

4. SDK Pattern Means You Manage Versions Per App

This is just a fundamental trade-off between SDK and Sidecar. With Sidecar, you can upgrade once everywhere. With SDK, every application has to upgrade its own dependency. That's more work, but again — it's the trade-off you make for no network hop. Worth it for many teams, but not for everyone.

Who Should Use This? Who Should Skip It?

After three years of using this in production, I've got pretty clear rules of thumb for whether Capa is a good fit for you:

✅ Go for it if:

You actually need hybrid/multi-cloud deployment — same code running on multiple clouds
You care about latency and want to avoid extra network hops
You're on the Java stack and don't want to deal with the operational complexity of Sidecar
You're a smaller team without the bandwidth to maintain a whole Sidecar infrastructure

❌ Probably skip it if:

You're only running on one cloud — you don't need this abstraction at all
You're already all-in on Dapr/Sidecar and it's working for you — no reason to switch
You need a huge ecosystem of pre-built components — Dapr has you covered there
You're not on Java — Capa is primarily Java-focused, other language support is limited

Some Architecture Thoughts I Picked Up Along The Way

One of the things I appreciate about Capa is its design philosophy. There are a few ideas here that've really stuck with me after using it for three years.

1. Mecha Architecture: An Evolution From Service Mesh

Capa's Mecha architecture is basically an evolution of the Service Mesh idea. Service Mesh pulls capabilities out into a Sidecar, Mecha pulls capabilities down into the SDK. There's no right or wrong here — it's just different choices for different scenarios.

What I find interesting is that this idea actually lines up pretty well with what's happening in AI right now with Mixture of Experts (MoE) — split capabilities into separate components, load what you need, don't load what you don't. Keep it clean.

2. Standard API + SPI Plugins: A Timeless Combination

This design pattern has been around forever, but it's still one of the best. The standard API keeps your business code stable, the SPI plugins give you extensibility. No matter how the underlying infrastructure changes, your business code doesn't need to move.

I've come to believe that good architecture isn't about being able to handle every possible change up front. It's about isolating the change points — when something changes, only that something changes. Everything else stays the same. Capa nails this.

3. Perfect Is The Enemy Of Good

Can Capa really abstract away 100% of the differences between cloud providers? No, of course not. Different cloud providers have different capabilities, and that's just reality. But here's what Capa does do — it abstracts away 80% of the common stuff that you would've had to write yourself. That 80% saves you 80% of your time. The remaining 20% was always going to be cloud-specific anyway.

That's just good pragmatism. You don't need theoretical perfection. You need something that solves most people's most common problems. Capa does that.

Wrapping Up: My Advice For Anyone Considering This

Honestly, after three years, I'm still really grateful for this project. It solved a real problem my team was having and saved us countless hours of work.

If you're currently drowning in hybrid cloud adapter code, and you're on the Java stack, you should definitely check Capa-Java out. I think it'll help you. Here's where to find it:

GitHub: https://github.com/capa-cloud/capa-java
Website: https://capa.rxcloud.group/

Before you dive in though, let me leave you with a couple of pieces of advice I wish someone had told me three years ago:

Do you actually need hybrid cloud? So many companies go "multi-cloud strategy" because it sounds good in board meetings, but they don't actually need it. Don't add complexity to your architecture just for the sake of it. If you're only running on one cloud, you don't need this.
SDK vs Sidecar — pick based on your team size. Big team with dedicated ops people? Sidecar probably makes sense. Smaller team that wants to keep things simple and lightweight? Go SDK. That's really it. No need to overcomplicate the decision.
Don't pick technology for the cool factor. Capa is great, but it's not the right choice for every situation. Be honest about your team's capabilities and your actual requirements.

I know hybrid cloud can be a real pain — I've been there. Hopefully this honest review helps you make a better decision than I did when I started.

What about you? Have you tried Capa-Java? Or are you still struggling with hybrid cloud adaptation madness? What's your go-to approach — SDK or Sidecar? I'd love to hear your experiences in the comments.

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud

KevinTen — Sat, 27 Jun 2026 19:04:46 +0000

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud

I want to start this with a confession — I used to be a huge Sidecar architecture fanboy. When Service Mesh became the hottest thing in cloud native, I read every blog post, watched every conference talk, and genuinely believed that Sidecar was the One True Way™ to solve all hybrid cloud problems.

Three years later, I've changed my mind. Not because Sidecar is bad — it's not. But because I've been working with Capa-Java every single day in production, and I've come to realize something important: there's more than one way to solve the hybrid cloud problem, and SDK-based approaches still have a lot to offer.

This isn't a "Sidecar bad, Capa good" take. It's a story about what I've learned from three years of production use, why we made the choices we made, and when you should consider going the SDK route instead of the Sidecar route.

How I Got Here: The Hybrid Cloud Pain That Started It All

Let me backtrack. Three years ago, my team was in that all-too-familiar spot: we needed to run the same application on both our private data center and a public cloud. Business requirements were clear — "we need to be able to deploy the same codebase anywhere, no rewrites."

Sounds simple enough, right? But when we actually started digging into it, things got messy quickly.

Every cloud provider has different APIs for configuration management. Different APIs for service discovery. Different APIs for message queues. Different APIs for distributed tracing. If you wanted to support multiple clouds, you either had to write a ton of adapter code yourself, or you went with a Service Mesh approach.

We looked at the popular Sidecar-based options. The architecture made sense — extract all the cross-cutting concerns into a separate process, your app just talks to localhost. But something felt off to us. We're a small team, and we'd have to operate these Sidecar containers on every single instance. That's more moving parts, more network hops, more things that can break.

Then I found Capa-Java. It took the opposite approach: instead of putting all the capabilities in a Sidecar, put them in an SDK that runs inside your application process. Same idea of separating capabilities from business logic, but different architectural placement.

I was skeptical at first. "That's just the old way of doing things," I thought. "Everybody knows Sidecar is the modern approach." But I tried it anyway, because honestly, we didn't have much to lose. Three years later, I'm still using it every day.

What Capa-Java Actually Does (In Plain English)

Let me explain what Capa-Java does in simple terms, because the project documentation can get a bit abstract.

At its core, Capa-Java gives you a single, consistent API for all the common infrastructure capabilities you need — configuration, service discovery, RPC, pub/sub, state management, you name it. Then, it uses a plugin system (SPI, if you're familiar with the term) to map that consistent API to whatever cloud provider you're actually running on.

So whether you're running on Alibaba Cloud, AWS, Tencent Cloud, or your own private data center, you write your business code once using the Capa API. When you deploy to a different environment, you just switch out the plugin — zero changes to your business logic.

That's the promise, anyway. Does it actually deliver on that promise? Yes — but with some caveats, which I'll get to later.

The key difference from Sidecar approaches is that everything runs in-process. When your application needs a configuration value, it calls the Capa SDK directly — no network call to localhost, no extra hop. That has implications for both performance and operations, which I want to dive into.

The Performance Argument: It's Not Just About Latency

People always bring up performance first when talking about in-process vs Sidecar, so let's get that out of the way. Yes, removing a network hop does lower latency. In our load tests, we saw P99 latency drop by 20-30% compared to the Sidecar setup we were benchmarking. That's not nothing — especially if you're working on something latency-sensitive like financial services or high-throughput APIs.

But here's what nobody talks about: it's not just the extra hop that adds latency. It's all the serialization/deserialization that has to happen. Your application puts together a request object, serializes it to send to the Sidecar, Sidecar deserializes it, does its work, serializes the response, sends it back, your app deserializes again. That's a lot of extra work that just disappears when everything is in-process.

But performance isn't why I stayed with Capa. The real win for us was operational simplicity.

The Operational Simplicity That Changed Everything

I think the industry has forgotten that every additional component you add to your stack has a cost. Not just a cost in resources — that's relatively cheap. A cost in operational cognitive load.

When you go the Sidecar route, you have to:

Deploy the Sidecar alongside every single application instance
Monitor the Sidecar separately
Update the Sidecar separately (and coordinate that with your application deployments)
Debug problems that span both your application and the Sidecar
Scale the Sidecar along with your application

That's not rocket science, but it's more stuff to worry about. If you're a large team with dedicated platform engineering folks, that's fine. They can handle that operational load. But if you're a small team like ours, where everybody is already wearing multiple hats? That extra operational load becomes a real burden.

With Capa-Java, there's no extra moving parts. The capabilities are just part of your application. When you deploy your app, you've already deployed Capa. When you scale your app, Capa scales with it. When you need to update Capa, you just update the dependency in your build file and deploy a new version of your app like you normally would.

It sounds simple, but that simplicity is actually revolutionary when you're living it. I spend way less time worrying about infrastructure, and more time actually building features that matter to our users.

The Trade-Offs Nobody Talks About

Okay, I've been positive so far, but I need to be honest — this approach isn't perfect. It's not for everybody. There are real trade-offs you need to consider, and I want to lay them out clearly.

First, polyglot architectures don't really benefit here. Capa is primarily for Java. If your organization has multiple services written in different languages — some Java, some Go, some Node.js — then you're going to need different SDKs for different languages. With a Sidecar approach, it doesn't matter what language your app is written in — the Sidecar just works. That's a real advantage for polyglot environments.

Second, version upgrades have to happen per-application. Because Capa is linked into your application, every application has to upgrade to the latest Capa version on its own schedule. With Sidecar, you can upgrade the Sidecar independently of the application — easier to get everyone on the same version. That's another trade-off: granular upgrade flexibility vs centralized version control. Which one you prefer depends on your organization's culture.

Third, the ecosystem is smaller. Let's be clear — Dapr has Microsoft behind it, it's in CNCF, it has a huge community, it supports dozens of different components. Capa is a community-driven project with a small core team. The number of components and plugins is smaller. The documentation isn't as extensive. If you need something really obscure, you might have to write the plugin yourself. That's just reality.

Fourth, it's still Java. Wait, what do I mean by that? I mean that if you've already decided to get off the Java ship because you want something lighter, faster, simpler — Capa-Java isn't going to change your mind. It's designed for Java teams that are already working in Java and want to stay in Java. It doesn't try to be everything to everyone.

Pros & Cons: The Honest Breakdown

Let me summarize this into a clean Pros & Cons list because I know that's what everybody actually scrolls down to read anyway. I learned the hard way that people appreciate straight talk, so here we go:

Pros:

✅ True write-once deploy-anywhere: Same business code runs on any cloud/environment, just swap plugins
✅ Lower latency: No extra network hop, no repeated serialization — P99 improves 20-30% in our tests
✅ Operational simplicity: No extra containers to deploy, monitor, or debug — just your app
✅ Proven Java pattern: Standard API + SPI plugins that've worked for decades, applied consistently
✅ Zero changes to your deployment process: Just build your Java app like you normally would
✅ Open source with active development: Been in production for 3+ years and still going strong

Cons:

❌ Java-only: Really only works for Java teams (though other language support is in the works)
❌ Smaller ecosystem: Fewer pre-built plugins compared to the big players like Dapr
❌ Per-application upgrades: No centralized Sidecar upgrades — each app upgrades on its own
❌ Not ideal for polyglot: Sidecar is better if you have many different languages in your architecture
❌ Small team project: No big company backing — it's built by developers, for developers

There you go — straight from the heart. No marketing fluff, just what you can actually expect.

How the Design Actually Works: The "Mecha" Architecture

Capa-Java is built on what they call the Mecha architecture, which is really just Service Mesh ideas reimagined for in-process. Instead of moving capabilities to out-of-process Sidecars, you move them into the SDK layer. Your business code depends only on the Capa API, not on any specific cloud provider's implementation.

What I find really elegant about this is that it's the classic Standard API + SPI Plugin pattern that we've been using in Java for decades. It's not a new pattern — it's a proven pattern that's stood the test of time. The difference is that Capa applies it consistently across all infrastructure capabilities.

Standard API gives you stability — your business code doesn't change when you change cloud providers. SPI plugins give you extensibility — if you need a custom adapter for your own private cloud infrastructure, you can write it without changing any of the core code or your business code.

I know this sounds obvious, but you'd be surprised how many "modern" architectures forget this basic separation. The best architectures are the ones that isolate the parts that change from the parts that don't. That's exactly what Capa does here.

Real-World Example: How We Use It in Production

Let me make this concrete with how we actually use Capa in production.

We have a core order processing system that needs to run in both our private data center (for regulatory reasons) and on AWS (for burst capacity). Before Capa, every deployment to a different cloud required us to go through and change all the infrastructure-related code. It would take us 3-5 days every time, and we'd always introduce new bugs.

Now? We write the business code once. When we deploy to our private data center, we include the private cloud plugins. When we deploy to AWS, we include the AWS plugins. That's it. The business code is exactly the same. Deployment time for a cross-cloud deployment went from 3-5 days to minutes. That's not an exaggeration — that's what actually happened to us.

Here's a code example that shows how simple it is. Want to call another service? It looks like this:

CapaRpcClient client = new CapaRpcClientBuilder()
    .build();

Mono<String> result = client.invokeMethod(
    "order-service",
    "createOrder",
    orderRequest,
    HttpExtension.POST,
    null,
    TypeRef.STRING
);

That code is exactly the same whether you're running on your private data center or AWS. The only difference is which plugin you have on your classpath. No conditionals, no environment-specific code, nothing. It's beautiful in its simplicity.

What about configuration? Same thing:

ConfigurationClient client = new ConfigurationClientBuilder()
    .build();

Mono<Configuration> config = client.getConfiguration("app.config");
config.subscribe(cfg -> {
    System.out.println("Config updated: " + cfg.getValue("timeout"));
});

Again, exactly the same code everywhere. The underlying implementation handles whatever configuration system you're using. You just write it once.

Adding a pub/sub subscription is just as straightforward:

PubSubClient client = new PubSubClientBuilder()
    .build();

client.subscribe("order-events", message -> {
    processOrderEvent(message);
    return Mono.empty();
}).subscribe();

I can't tell you how refreshing it is to have such a clean, consistent API across all these different infrastructure concerns. No more learning different APIs for different cloud providers. No more remembering that AWS does this one thing differently from Alibaba Cloud. Just one API to learn, one way to do things, and it works everywhere.

When Should You Actually Use Capa-Java?

After three years of using this every day, I've developed some pretty clear opinions on when Capa-Java makes sense, and when it doesn't.

You should probably consider Capa-Java if:

You're building Java applications and you need to run the same code on multiple clouds or environments
You're a small-to-medium team that doesn't have a huge platform engineering organization
You care about latency and want to avoid unnecessary network hops
You want operational simplicity — less moving parts to monitor and maintain
You like the idea of "just use the SDK" rather than running extra infrastructure
You want to keep your deployment pipeline simple without adding new tools

You should probably look elsewhere if:

You have a true polyglot architecture with lots of different languages
You have a large platform team that can handle the operational overhead of Sidecar
You need a huge ecosystem of pre-built components for every possible cloud service
You want centralized independent upgrades of infrastructure capabilities
You're not using Java (Capa is really Java-first)

The mistake I see people make all the time is they just go with whatever is currently trendy. "Sidecar is modern, so Sidecar is what I'll use." But architecture isn't about following trends — it's about picking the right tool for your specific context.

Context is everything. What works for a large FAANG-scale organization with hundreds of engineers doesn't work for a 5-person startup. What works for a polyglot shop with 20 different services in 10 different languages doesn't work for a Java shop that wants to stay Java.

What I've Learned After Three Years

After three years of using Capa-Java in production, what's the big takeaway for me?

It's this: The "best" architecture is the one that disappears into the background and lets you focus on what actually matters — building features for your users.

Capa-Java doesn't try to be everything to everyone. It doesn't try to solve every problem. It solves one specific problem really well — helping Java teams build hybrid cloud applications without all the extra complexity that comes with some of the more ambitious architectures.

I still think Sidecar has its place. For large organizations with complex polyglot environments, it's the right choice. But I also think the industry has kind of forgotten that simpler approaches can work really well in the right context.

Sometimes, putting the capabilities in-process is just... better. Not always, not for everyone, but sometimes. And when it's better, it's much better.

The other big lesson? Abstraction doesn't have to mean out-of-process. A lot of people seem to think that if you're not using Sidecar, you're not doing cloud native "correctly." That's nonsense. Cloud native is about building systems that can scale and adapt to change — it's not about mandating specific architectural patterns.

Capa-Java is cloud native — it embraces all the cloud native principles of portability and resilience — it just achieves them through a different architectural style. That's okay. We need more diversity in architectural approaches, not less.

Closing Thoughts and a Question for You

So here's the thing — I wrote this article because I don't see many people talking about the SDK-based approach these days. Everybody's talking about Sidecar, everybody's talking about Service Mesh, but the SDK approach that Capa-Java takes just works for a lot of teams, and it doesn't get much attention.

I'm not saying you should drop everything and switch to Capa-Java. What I am saying is that you should think carefully about your own context before you just follow the crowd. Maybe the simpler approach is actually the better approach for your team.

After three years, I'm still glad we went with Capa-Java. It's not perfect — nothing is — but it solves the problem we needed solved, it stays out of my way, and it lets me focus on building actual features instead of managing infrastructure.

If you're a Java developer working on hybrid cloud applications and you've been feeling like all the Sidecar stuff is just overkill for your team, I encourage you to check out Capa-Java on GitHub and see what you think. It's open source, it's free, and it might just solve the exact problem you're dealing with.

GitHub: https://github.com/capa-cloud/capa-java

Now I want to hear from you: What's your experience with hybrid cloud architectures? Have you tried both the Sidecar approach and the SDK approach? Which one worked better for your team, and why? I'm curious to hear different perspectives — there's no one right answer for everybody.

Drop a comment below and share your thoughts — I read every comment and I'll do my best to reply!

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

KevinTen — Sat, 27 Jun 2026 16:04:06 +0000

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

Let me start with a confession.

I've been building Java applications for hybrid cloud for over three years now, and honestly? I bought into the whole Sidecar hype like everyone else. "It's the future! Separate concerns! Your app doesn't need to worry about infrastructure!" Yeah, that's what I thought too.

So we went all in. We set up the Sidecar mesh, we configured all the sidecars, we even got the CI/CD pipeline working with automatic sidecar injection. Everything looked great on paper.

And then we went to production.

So here's the thing — we had thousands of lines of existing Java code. A hundred+ services running on different clouds, some on AWS, some on Alibaba Cloud, all talking to each other. The migration plan was supposed to take six months. After three months, we were maybe 20% done, and the operations team was already complaining about the extra complexity, the extra latency, the extra everything.

That's when I learned the hard way: Sidecar isn't always the answer. Sometimes, you just need a good SDK. And that's how I ended up contributing to Capa-Java, an open-source project that's been quietly solving hybrid cloud problems the SDK way for years.

What is Capa-Java Anyway?

Capa-Java is basically what you get when you take the Multi-Runtime API ideas from projects like Dapr and Layotto, but implement them as a plain old Java SDK instead of a Sidecar. The tagline says it well: "Write once, run anywhere."

Let me show you what I mean. With Capa-Java, you code against a standard API, like this:

import group.rxcloud.capa.sdk.CapaRpcClient;
import reactor.core.publisher.Mono;

// ... inject the client somehow ...

// Call a service on ANY cloud platform
Mono&lt;String&gt; result = capaRpcClient.invokeMethod(
    "my-target-service",       // Target app ID
    "sayHello",                // Method name
    "world",                   // Request data
    null,                      // Extra options
    new TypeRef&lt;String&gt;() {}   // Response type
);

// Get it synchronously if you want
String response = result.block();
System.out.println("Got response: " + response);

That's it. That's your code. Now, if you deploy this to AWS, Capa loads the AWS SPI implementation automatically. Deploy to Alibaba Cloud? It loads the Alibaba implementation. Want to run it locally with Dapr? Yep, there's a SPI for that too.

No code changes. Just swap out the dependency JAR. That's the whole idea.

The Big Debate: SDK vs Sidecar

I know what you're thinking. "But Sidecar is the future! Everyone's doing service mesh! Why would you go back to SDK?"

Look, I'm not here to say Sidecar is bad. It's not. It's amazing for what it does. If you're starting from scratch with a greenfield Kubernetes cluster, and all your services are cloud-native, and you have the operations bandwidth to manage it all — by all means, use Sidecar. It's great.

But let's talk about the real world. A lot of us don't have greenfield projects. We have brownfield. We have existing Java applications that have been running for years. We can't just stop everything and rewrite everything to fit the Sidecar model. The business won't wait. The budget isn't there.

Here's what I've learned after three years of this:

1. Operational Simplicity is Underrated

With Sidecar, every pod gets an extra container. That extra container needs CPU, memory, network. It needs monitoring. It needs updates. It can fail. If you have 100 services, that's 100 extra Sidecar processes running. Your operations cost just went up.

With Capa-Java, everything is just in-process. There's no extra container to manage. No extra network hop. Your existing deployment pipeline just works. If you can deploy a Java app, you can deploy Capa-Java. That's it.

2. Migration Isn't All-or-Nothing

One of the things I love about Capa is that you don't have to migrate everything at once. You can start with one service. See how it goes. Migrate another when you have time. There's no big bang cutover that keeps everyone up all night.

And because Capa follows the standard Multi-Runtime API, when Dapr (or whatever Sidecar project you like) matures to the point where you are ready to switch, you can do that too. Capa can already talk to Dapr. The migration path goes both ways.

3. Small Teams Don't Need Over-Engineering

I'm going to say something controversial here: not every team needs a service mesh. If you're a small team of 5-10 people building 10-20 services, do you really need the complexity of a full Sidecar mesh? Probably not. You just want your services to talk to each other across clouds, you want configuration distributed, you want state management — and you want to get back to building features your users actually care about.

That's where Capa really shines. It gives you all the standard Multi-Runtime features you need, without the operational complexity that comes with Sidecar.

How Does It Actually Work?

Alright, enough with the high-level stuff. Let's dig into the architecture. It's actually pretty simple.

Capa uses a layered architecture:

┌─────────────────────────────────┐
│      Application Layer          │  ← Your code, uses Capa API
├─────────────────────────────────┤
│      Capa SDK Layer              │  ← Core SDK, SPI definitions
├─────────────────────────────────┤
│      SPI Implementation Layer   │  ← Cloud-specific implementations
├─────────────────────────────────┤
│      Runtime Layer              │  ← Actual cloud services
└─────────────────────────────────┘

The key idea is separation of API from implementation. Your application code only ever depends on the standard Capa API. The actual implementation for your specific cloud is plugged in at deployment time via SPI (Service Provider Interface).

Let me show you a more complete example. Here's how you do state management with Capa:

import group.rxcloud.capa.api.state.StateManager;
import group.rxcloud.capa.model.state.SaveStateRequest;
import reactor.core.publisher.Mono;

// ... inject StateManager ...

// Save a state object
SaveStateRequest&lt;UserProfile&gt; request = SaveStateRequest.&lt;UserProfile&gt;builder()
    .storeName("my-state-store")
    .key("user:" + userId)
    .value(new UserProfile(userId, userName, email))
    .build();

Mono&lt;Void&gt; saveResult = stateManager.saveState(request);
saveResult.block();

// Get it back later
Mono&lt;UserProfile&gt; getResult = stateManager.getState(
    "my-state-store",
    "user:" + userId,
    new TypeRef&lt;UserProfile&gt;() {}
);

UserProfile profile = getResult.block();
System.out.println("Got profile: " + profile.getUserName());

See? That's just regular Java code. No annotations to clutter things up (though you can use them if you want them). No special framework requirements. Just a standard API that works anywhere.

Here's what it looks like with Pub/Sub:

import group.rxcloud.capa.api.pubsub.PubSubPublisher;
import group.rxcloud.capa.model.pubsub.PublishRequest;
import reactor.core.publisher.Mono;

// ... inject PubSubPublisher ...

// Publish an event — works with any cloud pub/sub service
PublishRequest&lt;OrderCreatedEvent&gt; request = PublishRequest.&lt;OrderCreatedEvent&gt;builder()
    .pubsubName("my-pubsub")
    .topic("orders")
    .value(new OrderCreatedEvent(orderId, customerId, amount))
    .build();

Mono&lt;Void&gt; result = pubSubPublisher.publishEvent(request);
result.block();

Same pattern, same API. Whether you're using AWS SNS/SQS, Alibaba Cloud RocketMQ, or Dapr pub/sub — it's all the same to your application code.

The Pros and Cons: I'm Being Honest Here

I said I wouldn't do the marketing hype thing, so let's cut to the chase. Here's what's good about Capa-Java, and what's not so good.

The Good (Pros)

✅ Write once, run anywhere — Seriously. Same code runs on AWS, Alibaba Cloud, Kubernetes, Dapr, whatever. Just change the SPI dependency. That's incredibly powerful for hybrid cloud.

✅ Low migration friction — You don't have to rewrite everything. You can migrate incrementally. For brownfield Java projects, that's a game-changer.

✅ No extra infrastructure — No sidecar containers to manage. No extra network hops. Your existing operations workflow just works. Lower latency, lower cost.

✅ Standard API following Dapr — The API design follows the community standard. If you already know Dapr, you already know how to use Capa.

✅ Decoupled API definitions — The API definitions are in an independent repository (cloud-runtimes-jvm) so the whole community can use them, not just Capa. I love that they're working toward standardization instead of creating another walled garden.

✅ Reactor native — Asynchronous by default, built on Project Reactor. You can use it reactively or block for synchronous calls — whatever fits your codebase.

The Not-So-Good (Cons)

⚠️ It's still an SDK in your process — Yeah, I know. Some people hate having infrastructure concerns in-process. If you're purist about separation of concerns, this isn't for you. That's okay, Sidecar exists for a reason.

⚠️ Alpha status on some features — Database and scheduled tasks are still alpha. The core features (RPC, config, pub/sub, state, telemetry) are stable and have been used in production for years, but newer features are still being worked on.

⚠️ Smaller community — Let's be real. Dapr has a huge company backing it and a massive community. Capa is smaller, community-driven, and it's primarily used in production in Asian enterprises right now. If you need enterprise support, that's something to consider.

⚠️ Limited SPI implementations so far — Right now, the main implementations are for AWS, Alibaba Cloud, and Dapr. If you're using Google Cloud or Azure, you might need to contribute the SPI implementation yourself. It's not hard — the SPI interface is pretty simple — but it's extra work.

My Personal Experience After Three Years

Honestly, I was skeptical at first. I'd bought into the Sidecar narrative completely. But after three years using Capa in production, I've changed my mind.

We started with 10 services. Now we have over 50 services on Capa. We didn't have to do any big bang migration. We just moved them one by one when we had time. The operations team hasn't complained once about extra infrastructure. Our latency actually went down because we don't have that extra Sidecar network hop anymore.

The biggest win? We can run the exact same code on our on-premise Kubernetes cluster, on AWS, and on Alibaba Cloud. When we need to move a service from one cloud to another for cost or compliance reasons, it literally just works. No code changes. That's worth its weight in gold.

I've also learned that "perfect is the enemy of good" in this space. Sidecar is theoretically perfect, but it's complex. Capa isn't theoretically perfect, but it works. It works for brownfield Java. It works for small teams. It works when you can't afford to stop everything and migrate to a whole new infrastructure.

Who Should Use This?

Based on my experience, here's who Capa-Java makes sense for:

You have an existing Java application (brownfield) that needs to run in hybrid cloud — This is the sweet spot. Low migration cost, incremental adoption.
You're a small team that wants Multi-Runtime features without Sidecar operational complexity — You don't need a big operations team to run Capa. If you can deploy Java, you can run Capa.
You want to experiment with Multi-Runtime architecture without committing to Sidecar — Start with Capa, learn the patterns, move to Sidecar later if you need it.
You need incremental migration to a cloud-native architecture — No big bang, no downtime, just move when you can.

And who shouldn't use it?

You're starting a brand new greenfield project on Kubernetes with plenty of operations resources — Go with Dapr or another Sidecar approach. It's probably a better fit long-term.
You need a lot of enterprise support or a huge community — Dapr has that right now, Capa doesn't (yet).
You strongly believe infrastructure should always be out-of-process — Fair enough! This project isn't for you, and that's okay.

Getting Started

If you want to try it out, it's dead simple. Just add the dependencies to your Maven pom.xml:

&lt;dependencies&gt;
  &lt;!-- Core Capa SDK --&gt;
  &lt;dependency&gt;
    &lt;groupId&gt;group.rxcloud&lt;/groupId&gt;
    &lt;artifactId&gt;capa-sdk&lt;/artifactId&gt;
    &lt;version&gt;1.0.7.RELEASE&lt;/version&gt;
  &lt;/dependency&gt;

  &lt;!-- Add the SPI implementation for your platform --&gt;
  &lt;!-- For example, the demo implementation: --&gt;
  &lt;dependency&gt;
    &lt;groupId&gt;group.rxcloud&lt;/groupId&gt;
    &lt;artifactId&gt;capa-sdk-spi-demo&lt;/artifactId&gt;
    &lt;version&gt;1.0.7.RELEASE&lt;/version&gt;
  &lt;/dependency&gt;
&lt;/dependencies&gt;

Then just start using the API like I showed you earlier. Check out the GitHub repository for more examples and documentation. There's also a Chinese README if that's more your speed.

Wrapping Up

Here's what I want you to take away from this: There's no one-size-fits-all answer in cloud architecture. Sidecar is amazing for what it does, but it's not the only answer. Sometimes, the simplest solution is the one that actually gets adopted.

Capa-Java isn't trying to replace Dapr or Sidecar. It's just offering another path. A path for brownfield Java. A path for incremental migration. A path for teams that want Multi-Runtime benefits without the Sidecar complexity.

After three years of using it in production, I'm sold. It solves a real problem that I had, and it solves it well.

What's Your Experience?

I'm curious — have you tried to do hybrid cloud with Java? Did you go the Sidecar route, or did you end up with something else? Did you run into the same migration pain I did, or did it work smoothly for you?

Drop a comment below and let me know. I'd love to hear different perspectives on this. Because honestly, the community gets better when we share both the successes and the failures, right?

This article is based on three years of production experience with Capa-Java. The project is open source and available on GitHub at capa-cloud/capa-java.

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

KevinTen — Sat, 27 Jun 2026 13:01:29 +0000

Capa-Java: Why Sidecar Isn't Always the Answer for Hybrid Cloud Java

Honestly, I've been building Java applications for hybrid cloud for about 7 years now, and I learned the hard way that everyone keeps talking about Sidecar architectures like Dapr and Layotto — and don't get me wrong, they're absolutely the future. But what if I told you that for most existing Java enterprise applications, migrating to a full Sidecar architecture tomorrow is basically impossible?

I've been using Capa-Java in production for three years, and today I want to share the real story: why this rich SDK approach to multi-runtime still matters, when you should use it instead of Sidecar, and the honest pros and cons I've discovered after all this time.

So here's the thing: Sidecar is the future, but we have billions of lines of existing Java

Let me start with my own pain point. A few years back, I was working on a traditional Java enterprise system that had accumulated about 10 years of code. We wanted to move to hybrid cloud — part on-prem, part public cloud — but every service was tightly coupled to our internal middleware APIs.

When Dapr came out, we got really excited. "Great!" we thought. "Let's just refactor everything to use the Sidecar pattern!" But then we started counting: thousands of services, millions of lines of code, dozens of different middleware dependencies... The cost of rewiring everything to go through the Sidecar was going to be enormous. We'd have to pause feature development for at least a year just for the migration.

That's when I found the Capa project, and it changed my thinking completely.

What actually is Capa-Java anyway?

Capa-Java is basically a rich SDK implementation of the Mecha architecture for Java. If you're familiar with Dapr's API concepts, you already understand most of it. The big difference is that instead of running as a separate Sidecar process, Capa runs inside your Java application as an SDK.

Let me show you what it looks like in code. Here's a simple service invocation example using Capa:

import group.rxcloud.capa.sdk.rpc.CapaRpcClient;
import reactor.core.publisher.Mono;
import group.rxcloud.cloudruntimes.utils.TypeRef;

// ...

// You just inject the Capa RPC client, it handles all the middleware complexity
CapaRpcClient capaRpcClient = applicationContext.getBean(CapaRpcClient.class);

// Invoke a service on ANY platform — AWS, Alibaba Cloud, Kubernetes, Dapr...
// The same code works everywhere without modification
Mono<String> result = capaRpcClient.invokeMethod(
    "my-target-service",      // Target app ID
    "sayHello",               // Method name
    "world",                  // Request payload
    TypeRef.STRING            // Response type
);

// Block for synchronous result (or just subscribe if you're reactive)
String response = result.block();
System.out.println("Got response: " + response);

See that? The code doesn't depend on any specific middleware provider API. If you deploy to Alibaba Cloud, Capa loads the Alibaba Cloud SPI implementation. If you deploy to AWS, it loads the AWS implementation. If you're on Kubernetes with Dapr, it just uses Dapr under the hood. Your business code doesn't change at all.

Write once, run anywhere. It sounds like a cliché, but that's exactly what you get here.

The architecture explained simply

Capa uses a layered approach that keeps things clean:

┌─────────────────────────────────────────────────────────┐
│         Application Layer (Your Business Code)          │
│                                                           │
│         Only depends on Capa's standard API              │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│               Capa SDK Layer (Core SDK)                  │
│   Standard API definitions, component loading, SPI      │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│         SPI Implementation Layer (Provider Specific)    │
│  AWS, Alibaba Cloud, Dapr, Kubernetes, custom...        │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│               Runtime Layer (Actual Services)            │
└─────────────────────────────────────────────────────────┘

This separation is what makes everything work. The API is standardized, but the implementation is pluggable. Currently, Capa-Java supports these stable features:

Feature	Description	Status
RPC/Service Invocation	Call services across environments	Stable ✅
Configuration	Dynamic configuration management	Stable ✅
Publish/Subscribe	Event messaging	Stable ✅
State Management	Distributed state	Stable ✅
Telemetry	Logging, metrics, traces	Stable ✅
SQL Database	Distributed SQL	Alpha 🚧
Scheduled Tasks	Job scheduling	Alpha 🚧

Getting started is dead simple

If you're using Maven, you just add two dependencies to your pom.xml:

<project>
  <dependencies>
    <!-- Capa core SDK with all standard APIs -->
    <dependency>
      <groupId>group.rxcloud</groupId>
      <artifactId>capa-sdk</artifactId>
      <version>1.0.7.RELEASE</version>
    </dependency>

    <!-- SPI implementation for your target environment -->
    <!-- This example uses the demo implementation for testing -->
    <dependency>
      <groupId>group.rxcloud</groupId>
      <artifactId>capa-sdk-spi-demo</artifactId>
      <version>1.0.7.RELEASE</version>
    </dependency>
  </dependencies>
</project>

That's it. You're ready to go. No extra processes to run, no infrastructure changes just to try it out. You can adopt it incrementally, service by service.

The real question: Should YOU use Capa-Java instead of Dapr/Layotto?

Honestly, this is where it gets interesting. I've been using this in production for three years, so let me break down the pros and cons honestly — no marketing fluff here.

Pros: What I love about Capa-Java

1. Incremental migration is actually possible

This is the big one. You don't need to rewrite your entire application overnight. You can start with one service, then gradually migrate more as you have time. For enterprises with massive legacy Java systems, this is a game-changer. We migrated 100+ services over the course of a year without stopping feature development. That would have been impossible with a full Sidecar rewrite.

2. No extra network hops

Since everything runs inside your JVM, there's no extra network call to a Sidecar proxy. Every invocation is direct. Latency is lower, and you don't have to deal with Sidecar performance issues under high load. I've seen cases where adding a Sidecar increased p99 latency by 2-3x — that doesn't happen with Capa.

3. It's just Java. Your ops team already knows how to handle it.

No new infrastructure to manage, no extra daemons to monitor, no additional configuration for deployment pipelines. It's just another dependency in your Java app. If you can deploy a regular Java app, you can deploy Capa. Your ops team doesn't need to learn a whole new stack just for hybrid cloud.

4. Seamless future migration to Sidecar

Here's the beautiful part: Capa is designed to be compatible with Dapr and Layotto. When your organization is ready to move to full Sidecar architecture, you just swap out the SPI implementation. Your business code doesn't need to change at all. You get a gradual migration path to the future, not a forced cliff.

5. Standard APIs that follow the community

The Capa project keeps API definitions in an independent repository called cloud-runtimes-jvm, and they follow Dapr's API standards. The goal is to make this a community standard, not lock you into another proprietary system. That's a design decision I really respect.

Cons: Where Capa-Java falls short

Nobody talks about the downsides, so I will.

1. You still have language coupling

Since it's an SDK, you're tied to Java (or whichever language you're using). If you have a polyglot environment with multiple languages, you need SDK implementations for each one. They do have alpha versions for Go and Python, but it's not as mature as the Java one. Sidecar gives you true language agnosticism out of the box. That's a real advantage.

2. The SDK versioning problem

When you have thousands of services, you have to manage the Capa SDK version across all of them. Upgrading to a new API version means redeploying every service. With Sidecar, you just upgrade the Sidecar once, and all services get the update immediately. This is where Sidecar really shines — it decouples infrastructure upgrades from application deployments.

3. Alpha features are still alpha

The core features (RPC, config, pub/sub, state, telemetry) are solid in production. But newer features like SQL database integration and scheduled tasks are still in alpha. They're not ready for mission-critical use yet. Dapr has a bigger community and more features fully baked.

4. Smaller community means more self-reliance

This is an open source project, but it's not as big as Dapr. If you run into problems, you can't just search Stack Overflow and find 100 answers. You might need to dig into the code yourself or file an issue. That's just the reality of smaller open source projects. I don't mind it, but it's something you should know going in.

So who is this project actually for?

Based on my experience over the past three years, I think Capa-Java is perfect for you if:

✅ You have an existing large-scale Java enterprise system that needs to move to hybrid cloud incrementally

✅ You don't have the bandwidth for a full Sidecar migration right now

✅ You want lower latency for service-to-service calls

✅ Your ops team isn't ready to manage additional Sidecar infrastructure yet

✅ You want a clear migration path to full Sidecar in the future when you're ready

You should NOT use Capa-Java if:

❌ You're starting a brand new project from scratch (use Dapr/Layotto with Sidecar — it's the future, after all)

❌ You have a polyglot architecture with many different languages

❌ You need the full set of multi-runtime features today (some are still alpha)

❌ You want a huge community with lots of existing examples and answers

I think that's pretty clear, right? No bullshit, just real advice.

My personal story: How this changed our hybrid cloud journey

Let me share a bit of my personal experience. Three years ago, we were stuck. We knew we needed to move to hybrid cloud, we knew our tight coupling to vendor-specific APIs was holding us back, but the estimated migration cost with Sidecar was just way too high. Our leadership wasn't going to approve a full year of just migration work — they needed features to keep the business moving.

When I found Capa, I was skeptical at first. "Another SDK?" I thought. "Isn't Sidecar obviously better?" But then I realized — the problem isn't that Sidecar is bad, the problem is that most of the world isn't ready for it yet. We're in transition. We have billions of lines of existing Java that need a path forward.

Capa gave us that path. We started with one service, got it working, then another, then another. Over the course of a year, we migrated all our services to Capa's standard API. Today, we can deploy the exact same code to our on-prem datacenter, to Alibaba Cloud, to AWS — whatever we need. Vendor lock-in is gone. We didn't stop delivering features. We didn't need to retrain our entire ops team. It just worked.

Honestly, I learned the hard way that architecture isn't just about what's theoretically perfect. It's about what works for your specific situation. Sometimes the "less perfect" architecture that lets you make incremental progress is actually the better architecture.

What's next for Capa-Java?

The project has been around for several years now, and the core features are stable in production. The maintainers are still working on it — they're gradually adding the alpha features and making them more robust. The independent API definition is really promising because it could become a standard that multiple projects can use, regardless of whether you're Team SDK or Team Sidecar.

If you're interested, you should check it out on GitHub:

GitHub: https://github.com/capa-cloud/capa-java

Go star it, open an issue if you find problems, and if you like the project, consider contributing. It's an open source project that fills a real gap that nobody else is really addressing.

Wrapping up

So here's the bottom line: Sidecar architecture is definitely the future of multi-runtime. But that future isn't here for everyone yet. For many of us working with large existing Java systems, we need a bridge between where we are now and where we want to go.

Capa-Java is that bridge. It's not trying to compete with Dapr or replace it — it's helping you get there gradually when a big bang migration isn't possible.

I've been using it in production for three years, and it has served me well. The honest pros and cons are all here — you can decide if it's right for your situation.

Now it's your turn

I'm curious — what's your experience with hybrid cloud migration? Are you working with massive legacy Java systems like I was? Have you tried to migrate to Dapr and gotten sticker shock from the migration cost? Or do you think the rich SDK approach is completely obsolete and we should all just go all-in on Sidecar?

Drop a comment below and let me know what you think. I read every comment and I'm looking forward to hearing different perspectives.

Domain Isolation: Why Bigger Context Windows Aren't Fixing Your AI Agent Chaos

KevinTen — Sat, 27 Jun 2026 10:07:15 +0000

Domain Isolation: Why Bigger Context Windows Aren't Fixing Your AI Agent Chaos

Honestly, I've been building AI agents full-time for about eight months now, and I need to get something off my chest. Every few weeks, another LLM provider announces a bigger context window. 128k! 200k! 1M tokens! And every time, my Twitter feed fills up with people saying "finally, we can just dump everything into context and be done with it."

But here's the thing — I tried that. You've probably tried that too. And it didn't work, did it?

Bigger context windows haven't solved my AI agent chaos. They just created a different kind of chaos: the context garbage dump problem. Everything's in there, but nothing makes sense. The AI pulls up yesterday's grocery list when you're trying to debug your production server. It mixes up your personal journal with your project planning. It's like having a desk where you just throw every paper you've ever touched — sure, everything's "in context," but good luck finding what you actually need.

After fighting this for months, my team and I built something different called OpenOctopus. It's a realm-native life agent system with domain isolation. And before you ask — no, it's not another prompt engineering trick. It's not tagging your messages with hashtags. It's not hierarchical organization. It's actual, physical (well, in database terms) isolation between different domains of your life.

Let me walk you through what we learned, why this works, and why I think domain isolation is the next big thing for personal AI agents.

The Problem: My 1M Token Context Window Still Couldn't Answer "What's my flight tomorrow?"

I learned this the hard way. Last quarter, I was traveling for a conference. I had my personal AI agent set up with everything — all my emails, my calendar, my travel confirmations, my shopping lists, my project planning documents. 800k tokens later, I asked a simple question:

"What time is my flight tomorrow?"

The AI started talking to me about a flight I had three months ago. It pulled the wrong confirmation. It mixed up the dates. It even tried to tell me I was flying out of the wrong airport.

I was furious. All those tokens, all that extra context, and it couldn't answer one simple question correctly. Why? Because everything was mixed together. The old flight confirmation was still in there, it was similar enough to the new one, and the attention mechanism just grabbed the wrong thing.

Have you had this experience? Let me know in the comments — I know I'm not the only one.

The worst part? This happens every single time you mix different domains. Your personal life gets mixed with work. Your side project gets mixed with your health tracking. Your vacation planning gets mixed with your tax documents. Everything bleeds into everything else, and the bigger the context window gets, the more opportunities there are for something irrelevant to sneak in and derail your entire conversation.

I tried all the conventional fixes before building OpenOctopus. None of them really worked:

What I Tried That Didn't Work

1. Prompt Engineering ("Only use recent messages")

Great in theory, terrible in practice. The AI says it's only using recent messages, but it still sneakily incorporates old irrelevant stuff. And you have to remind it every single time.

2. Tagging Each Message with Categories

Better than nothing, but you end up with tag explosion. Is this message about "work" -> "project-x" -> "backend" -> "debugging"? Who wants to tag every single message they send to their AI? That's more work than just doing the thing yourself.

3. Hierarchical Folders

The UI gets clunky. You have to remember where you put what. Cross-domain questions become a pain ("What meetings do I have this week that conflict with my kid's soccer games?"). You have to manually move stuff between folders. It just doesn't fit how human thinking actually works.

4. ML-Powered Automatic Retrieval

This is what most people are doing now with RAG. And don't get me wrong — RAG is great for documentation. But for a continuously running life agent? It's slow, it pulls the wrong chunks all the time, and you're still at the mercy of the embedding model's idea of "relevance."

After six months of trying every approach in the book, I had an epiphany: what if we just stop trying to make everything work together? What if we actually isolate different domains from each other by default, and only let them talk when we explicitly want them to?

That's exactly what OpenOctopus does.

How OpenOctopus Does Domain Isolation

So here's the core idea: every domain of your life gets its own realm. A realm is a completely isolated context space with its own database, its own conversation history, its own vector index. By default, realms don't talk to each other. There's a context firewall between them.

For example, I have these realms right now:

personal/family (kid stuff, family planning, home stuff)
work/openclaw (my main open source project work)
work/openoctopus (this project, obviously)
health/tracking (workouts, diet, doctor appointments)
travel/planning (current and future travel)
finance/taxes (you don't want this getting mixed with anything else, trust me)
side-project/english-agent (another AI project I've been working on)

When I'm working in the work/openoctopus realm, the AI literally cannot see anything from personal/family unless I explicitly pull something over. The context is clean. It's small. It's focused. No garbage. All the relevant stuff is there, and nothing else.

Does that sound restrictive? At first, I thought it would be too. But actually, it's exactly how human thinking works. When you're sitting at your desk working, you're not actively thinking about your kid's dentist appointment next week. You're focused on work. When you're at home with your family, you're not thinking about that tricky backend bug you're debugging. Your brain naturally switches between different contexts and keeps them separated.

We're just copying that into AI agents.

Let me show you what this looks like in actual code. Here's a simple example of creating a new realm and starting a conversation:

// Initialize OpenOctopus
import { OpenOctopus } from '@openoctopus/core';

const octopus = new OpenOctopus({
  dataPath: '~/.openoctopus/data',
  defaultModel: 'gpt-4o',
});

// Create a new realm for your side project
const projectRealm = await octopus.realms.create({
  name: 'side-project/my-cool-app',
  description: 'Building my new React app',
  domain: 'work',
});

// Start a conversation in the isolated realm
const conversation = await projectRealm.conversations.create({
  title: 'Debugging CORS error',
});

await conversation.addMessage({
  role: 'user',
  content: 'I keep getting this CORS error when I call my API from React. What am I doing wrong?',
});

// Only context from this realm is sent to the AI
const response = await conversation.generateResponse();
console.log(response.content);

See? The conversation is completely isolated. Only messages from this specific conversation in this specific realm are included. No random old stuff from other parts of your life sneaking in.

When do you want to share something between realms? That's easy — you explicitly share it:

// Get the flight confirmation from travel realm
const travelRealm = await octopus.realms.get('travel/planning');
const flightConfirmation = await travelRealm.messages.get('confirmation-123');

// Share it to your work calendar realm
const workCalendar = await octopus.realms.get('work/calendar');
await workCalendar.shareMessage(flightConfirmation, {
  note: 'Need to block time for this conference trip',
});

Explicit is better than implicit. If you want information to cross the context firewall, you have to explicitly allow it. No more accidental leakage.

The Real-World Edge Cases That Broke Our "Perfect" Architecture

Okay, I've been selling you this idea pretty hard. But this wouldn't be a honest article if I didn't tell you about all the edge cases that broke our initial design. Because when you build something that's supposed to handle real life, stuff gets messy.

We started with this beautiful, clean architecture. Every realm isolated, strict boundaries, everything neat and tidy. Then we started using it in real life, and we hit problem after problem. Here are the biggest ones we didn't anticipate:

1. The GPS Problem

Wait, GPS? What does that have to do with domain isolation? Well, when you're out and about, you might be at work, but you need to ask your agent "is there a coffee shop near here that's open?" That question doesn't belong exclusively to any single realm. It's a cross-domain question that needs location data from your system, nearby points of interest from somewhere, maybe your current calendar from work.

Our initial strict isolation completely broke here. We had to add a concept called global shared facts — things like your current location, current time, your basic preferences, your contact list, that are available to every realm by default. But they're read-only. They don't pollute your conversation history. That solved the GPS problem without opening the floodgates.

2. The Data Quality Nightmare

Different domains have different data quality standards. Your personal journal has messy, half-formed thoughts. Your work project documentation should be more structured. Your recipe collection needs different metadata than your travel itinerary. When everything is in one big context, the bad data pulls down the good data.

Our solution? Every realm can have its own schema and validation rules. You want your journal to be free-form? Fine. You want your project tasks to have status, priority, deadlines? Great. The schema stays with the realm, so you don't get cross-contamination.

3. The Trust Spiral Trap

This one's interesting. We started with really strict isolation — nothing gets out unless you explicitly approve it. What happened? Users got spammed with "this realm wants to share this information with that realm, do you approve?" every five minutes. It was so annoying that people just started clicking "approve always" and we were back to the original problem. Too much friction killed adoption.

We learned that perfect security isn't the goal — usable security is. So we added different trust levels between realms. If two realms are in the same general domain (like two different work projects), you can set them to "low-trust" (require approval for sharing) or "high-trust" (automatic sharing allowed). Most of the time, same-domain sharing is fine, so you don't get spammed. Cross-domain sharing (like work -> personal) still requires explicit approval. That's the sweet spot we found.

4. The Performance Degredation Curve

We started with every realm having its own separate vector index for RAG. That's great for isolation, but what happens when you have 20+ realms? You end up doing 20 different embedding searches when you do a cross-realm query. It gets slow. Real slow.

We solved this with a two-layer embedding approach: each realm has its own local index for conversation within the realm, and there's a shallow global index that only indexes the titles and explicit cross-realm shares. That keeps most queries fast (they're just local to the realm) and cross-realm queries still work without being unbearably slow.

The biggest lesson I learned from all these edge cases? Perfect is the enemy of good. We spent the first two months trying to build the perfect, theoretically pure isolated system. It didn't work in real life. We had to step back, accept that we couldn't handle every edge case perfectly, and build in graceful degradation.

That's a lesson I carry with me everywhere now. A system that works 95% of the time and is usable is way better than a system that works 100% of the time in theory but is so annoying nobody wants to use it.

Pros and Cons: Honest Evaluation After Eight Months of Daily Use

I'm not here to sell you on OpenOctopus as the perfect solution for everybody. It's not. It works really well for what it's designed for, but it has tradeoffs. Let me be completely transparent:

Pros

✅ Context actually stays clean — This is the big one. After eight months of daily use, I can honestly say that the "wrong information" problem has dropped by like 90%. When I ask my agent something in the work realm, it's only working with work stuff. No more random personal stuff popping up in the middle of a technical discussion.

✅ Better privacy by default — Because everything's isolated, if one realm gets compromised (unlikely, but possible), the damage is contained. Also, you don't have all your eggs in one basket encryption-wise. For sensitive stuff like finance or health, that's a big deal.

✅ Faster responses — Smaller, focused context means fewer tokens sent to the API. Lower costs, faster responses, less chance of hitting context limits. Everybody wins.

✅ It fits how I actually think — I don't think everything all at once. I switch between different areas of my life. OpenOctopus just gets that. It feels natural, not forced.

✅ It's open source and self-hosted — All your data stays with you. No third-party AI service holds all your personal life data. That's huge for me. I value my privacy.

Cons

❌ It's still early — This is beta software. We've been using it daily for eight months, but there are still rough edges. The UI isn't as polished as some commercial alternatives. You need to be a little bit technical to set it up right now.

❌ Extra step for cross-domain questions — If you frequently ask questions that span half a dozen different domains, you'll need to explicitly pull everything together. That's extra friction compared to just dumping everything into one big context. It's a tradeoff — clean default context vs convenience for cross-domain stuff. In practice, most of my daily questions are within a single domain anyway, so it's worth it for me. But your mileage may vary.

❌ More moving parts — Multiple databases, multiple indexes, multiple everything. There's more that can go wrong compared to a simpler single-context approach. We've stabilized it, but it's still more complex under the hood.

❌ Mobile app isn't done yet — We have a working progressive web app, but we don't have a native app in the app stores yet. If you want to use this primarily on your phone, you might be frustrated right now. We're working on it, though!

So who is this for? If you're a builder, someone who likes to tinker, you value your privacy, you've been frustrated with AI agent context chaos — you'll probably like OpenOctopus. If you just want something that works out of the box with a polished UI and you don't care about self-hosting, this probably isn't for you yet. We'll get there, but we're not there yet.

My Personal Journey: Why I Kept Working On This Even When It Seemed Stupid

Honestly, there were multiple points where I thought about just abandoning this whole project. It seemed like everybody else was going the "bigger context window" route, and who was I to argue? Maybe I was just solving a problem that didn't need solving.

But I kept coming back to that flight I mentioned earlier. 800k tokens, and it couldn't even tell me what time my flight was. That experience stuck with me. I knew there had to be a better way. I was the user that wasn't being served by the current approach.

And the more I talked to other people building personal AI agents, the more I realized other people had the same problem. They just weren't talking about it as much as they were talking about the latest context window size announcement.

So I kept going. I got up every morning, worked on it, fixed another edge case, refactored another piece of the architecture, and slowly but surely, it started to actually work. Not just in theory, but in my daily life.

Now I use it every single day. It's how I organize all my AI agent work. It keeps my head clear, and it keeps my context clean. And that's why I wanted to share it with you.

Want to Try It?

If you've been struggling with context chaos in your personal AI agent, if bigger context windows haven't solved your problems, if you're tired of your AI pulling up irrelevant garbage from six months ago — go check out OpenOctopus on GitHub.

The project is here: https://github.com/reware-frame/OpenOctopus

It's completely open source, licensed under MIT, so you can do whatever you want with it. We've got a getting started guide in the README that should walk you through setting it up if you want to give it a spin.

What Do You Think?

I'm curious — have you tried building a personal AI agent? Have you run into the context garbage dump problem? What approach did you take to fix it? Do you think domain isolation makes sense, or am I barking up the wrong tree here?

Drop a comment below and let me know. I read every comment, and I'm always interested in hearing other people's experiences with this stuff. Maybe you've got a better approach, and I'd love to learn about it.

Happy building!

Building Dog Agent: Why I Built an AI-Powered Community for Dog Walking Adventures (And What Broke Along The Way)

KevinTen — Sat, 27 Jun 2026 01:12:27 +0000

Building Dog Agent: Why I Built an AI-Powered Community for Dog Walking Adventures (And What Broke Along The Way)

Honestly, I never thought I'd be writing a technical article about building an app for my dog. Three months ago, if you told me I'd spend 80+ hours coding something just so my golden retriever could find new walking routes, I'd laugh at you. But here we are — and honestly, it's been one of the most surprisingly fun side projects I've built in years.

Let me back up. My dog, Max, is three years old and has the energy of a thousand puppies. Every single day we go walking, and every single day he expects a new route. If we repeat the same route too many times, he gets bored halfway through, plants his butt on the sidewalk, and refuses to move. I'm not kidding — that's actually what started this whole project.

I tried all the usual apps: AllTrails, Google Maps, even some dog-specific walking apps. But none of them really solved my problem. I didn't need popular hiking trails 50 miles away from the city. I needed to find interesting, new neighborhood walks within a 2-mile radius, shared by other local dog people who actually walked them. And I wanted AI to help recommend routes that matched our energy level — sometimes we want a quick 20-minute loop, sometimes we want a two-hour adventure with lots of grass and places to swim.

So I did what any engineer does when their dog is bored: I built my own app. That's how Dog Agent was born.

What is Dog Agent?

Dog Agent is an open-source AI-powered community for dog walking adventures. It lets you:

Share your favorite dog walking routes
Discover new routes near you based on location and distance
Get AI recommendations that match your energy level and dog's personality
Save your favorite routes and keep track of where you've gone
All photos are automatically compressed to save on storage (trust me, you need this)
Privacy-first: all your personal data stays under your control, we don't sell anything to anyone

The tech stack looks like this:

Backend: Go (because it's fast, simple, compiles to a single binary — perfect for side projects)
Mobile App: React Native (so it works on both iOS and Android, I only have to write it once)
Database: PostgreSQL with PostGIS extension for spatial queries (more on this magic later)
AI: OpenAI text-embedding-3-small for route recommendations + cosine similarity matching
Storage: Cloudflare R2 for photos (no egress fees — game-changer for side projects)

You can check out the full code here: https://github.com/kevinten10/dog-agent

Honestly, it's still in beta. Android testing is mostly done but we're ironing out a few kinks. But it already works well enough that a handful of local dog owners are using it every day. So I wanted to share what I learned building it — the good, the bad, and the "why did my bill jump $80 in one month" part.

The Good Stuff: PostGIS Changed Everything

When I started this project, I knew I'd need to do spatial queries — like "find all routes within 2 miles of my current location". I started off thinking I'd need a separate spatial database like Elasticsearch or something fancy. But then I remembered: PostgreSQL has PostGIS, and it's actually really good at this stuff.

I learned the hard way that you don't need a fancy specialized spatial database for most side project spatial needs. PostGIS does everything I need, and it's already part of your normal PostgreSQL setup if you enable the extension.

Here's basically how I set it up:

-- Enable PostGIS extension
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS postgis_topology;

-- Create routes table with geography column for location
CREATE TABLE routes (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(255) NOT NULL,
  description TEXT,
  location GEOGRAPHY(Point, 4326) NOT NULL, -- 4326 is WGS84, standard for GPS
  distance_km DOUBLE PRECISION NOT NULL,
  estimated_minutes INTEGER NOT NULL,
  difficulty INTEGER NOT NULL, -- 1-5 scale
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  created_by UUID REFERENCES users(id)
);

-- Create spatial index — this makes queries fast!
CREATE INDEX idx_routes_location ON routes USING GIST (location);

And then querying for nearby routes is so simple:

// Go code example: find all routes within 2km of current location
query := `
  SELECT 
    id, name, description, distance_km, estimated_minutes, difficulty,
    ST_Distance(location, ST_SetSRID(ST_MakePoint($1, $2), 4326)) AS dist
  FROM routes
  WHERE ST_DWithin(location, ST_SetSRID(ST_MakePoint($1, $2), 4326), $3 * 1000)
  ORDER BY dist
  LIMIT 20
`
rows, err := db.Query(query, lng, lat, radiusKm)

That's it. That's the whole spatial query. 100x simpler than I thought it would be, and it's fast. Even with a few thousand routes, queries return in 20-30ms. I was shocked.

The key lesson here: don't overcomplicate things. PostGIS does 99% of what most people need for spatial applications. You don't need a fancy specialized solution until you have millions of routes. For a side project like this, it's perfect.

The AI Part: Simple is Better Than Complex

Here's the thing about AI recommendation for something like this: you don't need to train a whole model from scratch. I thought about fine-tuning a model to learn what kind of routes Max likes, but honestly... that's overkill.

What I do instead is:

When a user creates a route, they write a short description: "flat walking trail with lots of grass, creek access for dogs, not too crowded"
I generate an embedding for that description using OpenAI's text-embedding-3-small
When a user says "I want a flat walk with creek access", I generate an embedding for their query
I compute cosine similarity between the query embedding and all route embeddings
Sort by similarity + distance, return the top matches

That's it. That's the whole AI recommendation system. ~50 lines of code, and it works shockingly well.

Here's the embedding generation code in Go:

package main

import (
    "context"
    "github.com/sashabaranov/go-openai"
)

type EmbeddingService struct {
    client *openai.Client
}

func NewEmbeddingService(apiKey string) *EmbeddingService {
    return &EmbeddingService{
        client: openai.NewClient(apiKey),
    }
}

func (e *EmbeddingService) CreateEmbedding(ctx context.Context, text string) ([]float32, error) {
    resp, err := e.client.CreateEmbeddings(ctx, openai.EmbeddingRequest{
        Input: []string{text},
        Model: openai.SmallEmbedding3,
        Dimensions: 512,
    })
    if err != nil {
        return nil, err
    }
    return resp.Data[0].Embedding, nil
}

// Cosine similarity between two embeddings
func CosineSimilarity(a, b []float32) float32 {
    var dotProduct float32
    var magA float32
    var magB float32
    for i := range a {
        dotProduct += a[i] * b[i]
        magA += a[i] * a[i]
        magB += b[i] * b[i]
    }
    if magA == 0 || magB == 0 {
        return 0
    }
    return dotProduct / (sqrt(magA) * sqrt(magB))
}

I use 512 dimensions instead of the full 1536 — this cuts embedding size by 2/3, and I haven't noticed any difference in recommendation quality for my use case. The cost? Insignificant. 512 dimensions is 512 floats per embedding — that's 2KB per route. Even with 10,000 routes that's 20MB. Nothing.

And the cost for the OpenAI API? $0.00002 per embedding. So even generating 1,000 embeddings costs two cents. Are you kidding me? That's nothing.

I was worried this approach would be too simple, but honestly — it works better than I expected. Users get recommendations that actually match what they're asking for, and I don't have to maintain any complex AI infrastructure.

The Surprising Pains I Didn't Expect

Okay, let's get real. Not everything went smoothly. Here are the three biggest pains that caught me completely off guard.

1. Mapbox Pricing Got Me

I started off using Mapbox for maps in the React Native app. Their free tier is 50,000 monthly active users — that sounds like way more than I'd ever need for a local dog walking app, right? Wrong.

Wait, no — actually, I misread the pricing. Mapbox pricing is per month, and it's based on monthly active users. But the catch: if you go over the free tier, you don't just get charged for the overage — you get charged retroactively for all your users. So when I had 12 local dog owners start using it regularly, I got a bill for $80. For twelve users. That's more than my entire server cost.

I was shocked. I knew Mapbox wasn't cheap, but I didn't expect that pricing model. So I'm currently evaluating alternatives — Google Maps has a better pricing model for small apps, and there's also MapLibre which is open source. I haven't switched yet, but that's definitely on the roadmap.

Lesson learned: always read the fine print on pricing before you integrate a third-party service. Even if it says "free tier", make sure you understand what happens when you grow past it.

2. Image Compression is Non-Negotiable

When users upload photos of their walks and their dogs, those photos are huge — like 12MP from a modern phone, 4-5MB per photo. If you just store them as-is and serve them directly, you'll burn through storage and bandwidth super fast.

I learned this the hard way after a week: 50 photos uploaded, and we'd already used 200MB of storage. That doesn't sound like much, but it adds up quickly — especially if the app grows.

So I added automatic image compression on the client before upload. In React Native, it's pretty straightforward with the react-native-image-compressor package:

import ImageCompressor from 'react-native-image-compressor';

const compressedImage = await ImageCompressor.compress(imageUri, {
  quality: 0.7,
  maxWidth: 1200,
  maxHeight: 1200,
});

That's it. This drops most photos from 4-5MB down to 200-300KB without any noticeable quality loss for mobile viewing. 10x smaller. Game-changer. I should have done this from day one — don't make the same mistake I did.

3. Privacy Matters — Even for a Dog Walking App

Because this is a community app, users share their current location and their favorite routes. I thought about making all routes public by default, but then I thought: what if someone shares their favorite secret spot that's really quiet, and then a hundred people show up the next weekend? That ruins it for everyone.

So I added privacy controls: you can choose for each route whether it's:

Public (visible to everyone)
Unlisted (visible only to people with the link)
Private (only visible to you)

This way, people can keep their favorite secret spots secret if they want. I think that's really important — especially for things like hiking and dog walking where overuse can ruin a good thing.

And because all user authentication is done with good old email/password and JWT, and photos are stored in my own Cloudflare R2 bucket, I don't have to send user data to a third party for storage. That's a win for privacy, and it keeps costs predictable.

Pros and Cons: Let's Be Honest

I think too many project READMEs just list all the good stuff and ignore the bad. So here's my honest Pros and Cons breakdown for Dog Agent, and for this approach to building an AI-powered community app:

Pros

Solves a real personal problem: This isn't a project built for "learn AI" or "get a VC deal" — I built it because I actually needed it. That keeps you motivated when things get frustrating.
Simple architecture, easy to hack: No fancy microservices, no Kubernetes, just Go backend + React Native app + PostgreSQL. You can get the whole thing running locally in 10 minutes if you know what you're doing.
Privacy by design: Users control their own data, no selling user data, everything is open source so you can self-host if you want.
Cost is almost nothing: For 100 active users, my total monthly cost is: Server $5, Cloudflare R2 $0.10, OpenAI embeddings $0.50. That's it. Way cheaper than I expected.
AI doesn't have to be complicated: Simple embeddings + cosine similarity gets you 80% of the way for most recommendation use cases, and it's super cheap and easy to maintain.

Cons

Still beta, Android not fully tested: I'm an iOS user, so Android testing has been slower. If you're an Android developer and want to help, PRs are welcome!
Mapbox dependency still needs replacing: As I mentioned earlier, the pricing is scary for growth. We're working on switching to MapLibre.
No social features yet: No comments, no likes, no following other dog walkers. That's on the roadmap, but it's not done yet.
Requires your own OpenAI API key if you self-host: That's not a big deal for developers, but it does mean non-technical users can't just spin it up easily.
Recommendation quality depends on user descriptions: If people write bad descriptions, recommendations are bad. That's inherent to this approach. I'm working on automatically extracting better descriptions from metadata, but it's not perfect yet.

What I Learned Building This

Honestly, this project surprised me. I started it as a silly side project to keep my dog happy, and I ended up learning a bunch of stuff I didn't expect:

The best side projects solve your own problems: If you have a real problem you're actually annoyed by, you'll stick with it longer and build something better than if you build something you don't care about just because it's trendy.
Simple almost always beats complex: I didn't need a fancy vector database — PostgreSQL does the job just fine for this scale. I didn't need to fine-tune a large language model — simple embeddings work great. Keep it simple.
Pricing surprises will get you: Always check third-party pricing multiple times. I thought I understood Mapbox pricing, and I still got surprised.
Privacy isn't just for "big apps": Even a small dog walking app needs to think about privacy — both for users and for the places they share. Giving users control over who can see their routes is the right thing to do.
Dog owners love talking about their dogs: Who knew? Local dog owners have been really excited about this app, and the community is growing faster than I expected. People actually want this.

Try It Out

If you're a dog owner who gets bored walking the same route every day, or you're a developer who wants to hack on an open source AI side project, go check it out: https://github.com/kevinten10/dog-agent

It's completely open source, you can self-host it, you can contribute, you can fork it and build your own version. All I ask is that you star the repo if you think it's interesting — that helps other people find it.

Wrapping Up

So here we are — three months and 80+ hours later, we have a working AI-powered dog walking community app that my dog actually approves of (he still sometimes refuses to move, but that's just him being a golden retriever). It's not perfect, but it works, it solves a real problem, and I had a ton of fun building it.

I think that's what side projects are supposed to be about, right? You don't have to build the next unicorn. Sometimes you just build something that makes your daily life a little better, and maybe it helps other people too.

Your Turn

Have you ever built a side project to solve a really specific personal problem? Did it turn into something bigger than you expected? And if you're a dog owner — have you ever had your dog refuse to walk because they were bored of the route? Let me know in the comments below!

Building Dog Agent: Why I Built an AI-Powered Community for Dog Walking Adventures (And What Broke Along The Way)

KevinTen — Fri, 26 Jun 2026 22:13:43 +0000

Building Dog Agent: Why I Built an AI-Powered Community for Dog Walking Adventures (And What Broke Along The Way)

Honestly, I never thought I'd end up building a whole community app just because my golden retriever, Max, kept getting bored on the same walking routes every single day.

It started innocently enough — every morning we'd hit the same park trail, every evening the same neighborhood loop, and after three months Max would just stop halfway and look at me like, "Are we seriously doing this again?" I get it, dude. Variety is the spice of life, even for dogs.

So I began asking other dog owners in my area where they walked. Turns out, everyone has their secret spots — hidden trails along the river, quiet country roads with great smells, abandoned railway lines turned greenways that no one really talks about. But there wasn't a good place to share these spots specifically for dog walking. Google Maps doesn't care if a route has too many busy road crossings, or if there's livestock you have to watch out for, or if the mud gets so bad after rain that your dog will come home looking like a chocolate bar.

That's how Dog Agent started. Three months later, here I am with a working prototype, and a whole bunch of unexpected lessons learned. Let me share it all with you — warts and all.

What is Dog Agent anyway?

Dog Agent is a mobile-first community where dog owners can share, discover, and get AI-powered recommendations for dog walking routes. The core idea is simple:

Share your favorite dog walks with details that matter to dog owners (surface type, difficulty, traffic, poop bag stations, water access, dog-friendly rules)
Discover new routes near you filtered by your dog's size, energy level, and your walking style
AI generates personalized route recommendations based on your preferences, location, and recent walks
Privacy-first: your location data stays on your device unless you choose to share a route

GitHub repo: https://github.com/kevinten10/dog-agent

Currently it's a side project, completely open source under the MIT license, built with React Native + Go backend + PostgreSQL + PostGIS for spatial queries. I've been using it with my local dog walking group for about a month now, and we've already discovered 17 new great walking routes within 20km that none of us knew existed.

Stars: currently sitting at 5 (all from my dog walking friends, which is honestly more than I expected for a random side project)

Why build another route-sharing app when we already have AllTrails, Strava, Wikiloc?

Great question. I've used all those apps, and they're great for hiking, running, cycling — but dog walking has different priorities.

Let me give you an example: On AllTrails, a 5-star trail might go through an area where dogs are strictly not allowed off-leash, but that doesn't show up anywhere prominent. A "beginner" hiking trail might have 500 stairs — which is fine for fit humans but terrible for an older dachshund with joint issues. A popular route might cross three busy highways without pedestrian crossings — again, that information isn't highlighted anywhere because it's not relevant to hikers, but it's make-or-break for daily dog walking.

Here's what matters to dog owners that other apps don't track well:

Off-leash friendliness: Is this route legally off-leash? Are there always other dogs around? Is it usually quiet enough to let your dog run safely?
Surface information: How much asphalt vs gravel vs grass vs mud? Bad surfaces can hurt dog paws, especially after rain.
Road crossings: How many busy road crossings are there? Is there a safe underpass or overpass?
Facilities: Are there poop bag stations? Drinking water for dogs? Parking close to the trailhead?
Dog rules: Are there seasonal restrictions (lambing season, bird nesting areas where dogs must be on-leash)?
** Hazards**: Livestock, wildlife (porcupines, ticks, poison ivy), steep drops that aren't good for clumsy dogs

These aren't things that matter much to hikers who are just passing through, but they matter a lot when you're looking for a daily walking spot you can bring your best friend to.

So I built Dog Agent to fill that gap.

Tech stack choices: What worked and what surprised me

Let's talk tech — because that's what you're really here for, right?

I chose:

Backend: Go — I wanted something lightweight that could handle lots of concurrent spatial queries, and easy deployment on Fly.io. This has worked great so far. Go's standard library is solid, the binary is tiny, cross-compilation to arm64 works perfectly for my VPS.
Database: PostgreSQL + PostGIS — I knew we'd be doing tons of "find all routes within 10km of me" queries, and PostGIS does this out of the box perfectly. No need for a separate spatial database.
Mobile app: React Native — I know React already from web work, and Expo makes deployment so much easier for a solo dev. I can get test builds on my phone in minutes.
AI recommendation: Currently using OpenAI embeddings + simple cosine similarity to match user preferences to routes. Nothing fancy, and it's already working better than expected.

The good

PostGIS has been a joy. I was worried spatial queries would be slow with hundreds of routes, but even with a thousand routes within 50km, it returns results in under 30ms on my cheap $5/month VPS. Here's what a typical nearby query looks like:

// Find all routes within given distance from point
func (q *Queries) ListRoutesNearby(lng float64, lat float64, distance float64, limit int) ([]Route, error) {
    // PostGIS makes this literally one line
  query := `
    SELECT *
    FROM routes
    WHERE ST_DWithin(
      geography(location),
      ST_SetSRID(ST_MakePoint($1, $2), 4326),
      $3
    )
    ORDER BY ST_Distance(geography(location), ST_SetSRID(ST_MakePoint($1, $2), 4326))
    LIMIT $4;
  `
  // ... execute query and scan rows
}

That's it. PostGIS handles all the geometry, indexing, distance calculations. I didn't have to implement any of that myself. Absolutely love it.

Go has also been perfect. The entire backend API is about 1200 lines of code, which is tiny. It handles everything from route CRUD to image upload to spatial queries to authentication. Compiles to a single binary, deploy with Docker in 2 minutes.

The bad

React Native has been... fine, but there are definitely things I'd do differently next time.

The biggest surprise? Mapbox is really expensive once you get more than a few thousand active users. I started with their free tier, which is fine for development, but if this ever actually grows it's gonna cost more than my VPS, database, and everything else combined. I'm currently looking at switching to Google Maps or OpenStreetMap-based solutions, but that means rewriting the map layer. Lesson learned: check the pricing before you pick the dependency.

Another gotcha: React Native navigation has so many edge cases. I can't tell you how many hours I've spent debugging deep linking and status bar height issues on different Android versions. For a solo dev, maybe Flutter would have been faster to get moving — but I already knew React, so here we are.

The ugly

The biggest mistake I made early on was not handling image compression properly. Users would upload 12MP photos from their phones straight to the server, and suddenly my 80GB VPS disk was 90% full in two weeks from like 50 photos. Oops.

Fixed that with client-side compression before upload:

// In React Native, using react-native-image-resizer
const resizeImage = async (uri: string) => {
  const response = await ImageResizer.createResizedImage(
    uri,
    1200, // max width
    800,  // max height
    'JPEG',
    80    // quality
  );
  return response.uri;
};

That reduced average photo size from ~3MB to ~200KB, problem solved. But I wasted a weekend panic-deleting old photos to free up space. Always compress images before upload, kids.

AI recommendations: Simpler is better

Originally I thought I'd need a huge fancy ML model to recommend routes to users. "AI-powered" is in the name, after all. But turns out, you don't need that much complexity to get useful recommendations.

Here's what I do now:

When a user adds preferences (dog size, energy level, favorite terrain, hates busy roads), generate an embedding from those preferences using text-embedding-3-small.
When a user adds a route, generate an embedding from the route description and all the metadata tags.
To get recommendations, just compute cosine similarity between the user's preference embedding and all the route embeddings nearby, sort, return top 10.

That's literally it. 50 lines of code. And it works shockingly well.

Here's the core of it:

import (
    "math"

    "github.com/kevinchan08/go-cosine"
)

func getRecommendations(userEmbedding []float32, routes []RouteWithEmbedding, limit int) []RouteWithEmbedding {
    type scored struct {
        route RouteWithEmbedding
        score float64
    }
    var scores []scored
    for _, r := range routes {
        similarity := cosine.Distance(userEmbedding, r.Embedding)
        // cosine distance is 0-1, lower = more similar
        // convert to similarity score 0-1 higher = better
        score := 1 - similarity
        scores = append(scores, scored{route: r, score: score})
    }
    // sort descending by score
    sort.Slice(scores, func(i, j int) bool {
        return scores[i].score > scores[j].score
    })
    // return top N
    var result []RouteWithEmbedding
    for i := 0; i < len(scores) && i < limit; i++ {
        result = append(result, scores[i].route)
    }
    return result
}

I was honestly skeptical this would work — but because both the user preferences and the route descriptions are natural language, the embeddings capture semantic similarity really well. If a user says "my dog loves swimming and we're looking for river trails", the embedding ends up close to routes that mention "river" "swimming" "water" in their descriptions.

It's not perfect, but for a side project it's more than good enough. And it's cheap — each embedding is like a penny or less for hundreds of routes. I don't need to fine-tune any models, don't need to run any GPUs, just call the OpenAI API once per route/perference and done.

So here's the thing: I learned the hard way that you don't need GenAI for everything, but when you use it for what it's good at (turning natural language into vectors that capture meaning), it's magical how simple you can keep things.

Pros & Cons: Honest talk about this project

Let's cut the marketing fluff — here's what works and what doesn't.

Pros

✅ Privacy-first by design: You don't have to share your location or your walks if you don't want to. All personal data stays on your device unless you explicitly choose to contribute.

✅ Really simple data model: The entire schema is like 8 tables. Easy to maintain, easy to hack on if you want to add features.

✅ Works offline: Once you load nearby routes, you don't need data service to browse them — great for remote walking areas.

✅ Open source & free: MIT license, no open-core nonsense, all code is on GitHub. You can run your own instance if you want, totally free.

✅ Incremental adoption: You can use it just to discover routes, you don't have to share any of your own if you don't want to. No pressure.

✅ Spatial queries just work: PostGIS does all the heavy lifting, it's fast even on cheap hardware.

Cons

❌ Still beta: It's three months old, built by one person in spare time. There are bugs, and some features aren't done yet (like social features, following other users, commenting).

❌ Mapbox pricing: As I mentioned earlier, if it grows I either have to switch map providers or start charging, which I didn't want to do. Current version still uses Mapbox for now, but migration is on the todo list.

❌ Only iOS currently: Android build is almost done but not fully tested yet. Solo dev problems — I only have an iPhone to test on.

❌ AI recommendations are basic: It works okay for now, but it could be smarter. It doesn't learn from your actual walked routes yet, just your stated preferences.

❌ No offline maps caching: If you go really off-grid with no cell service, you can't see the map tiles, only the route line. That's on the todo list but not done yet.

My personal lessons building this project

So here's what I learned starting this project from zero three months ago:

First, solve your own problem first. I built this because Max and I actually needed it. Every feature I added was because I hit the problem myself. That keeps you focused, you don't build a bunch of useless features no one actually uses. I've built so many projects in the past solving other people's hypothetical problems, and most of them went nowhere. This one's different because I use it every single day.

Second, side projects need scope control. I originally wanted to add social login, sharing, commenting, following, direct messaging, route rating, everything. I cut all that except the core — share routes, discover routes, recommend routes. That's it. The entire project took three months from idea to working prototype because I kept it small. You can always add features later.

Third, don't reinvent the wheel. PostGIS already does spatial queries perfectly. OpenAI already does embeddings perfectly. Expo already does mobile deployment. Why build your own spatial index when PostGIS has already had decades of work put into it? Use the best tool for each job, even if it means calling an API.

Fourth, expect the unexpected. I never thought map pricing would be my biggest problem this early on. I never thought image compression would fill my disk in two weeks. Every project has these gotchas — that's part of the fun, right? If everything went according to plan it'd be boring.

Honestly, I'm having a lot of fun with this. It's my first full mobile app from scratch, first time using PostGIS seriously, first time adding AI recommendations to a real project I use myself. Even if no one else ever uses it, it's already been worth it for what I've learned.

What's next for Dog Agent

Right now it's just me working on it in my spare time after work and on weekends. The immediate next steps are:

Finish testing Android build and get it on the app stores
Switch map providers to something more affordable for growth
Add offline map tile caching
Add basic social features — commenting on routes, adding photos after your walk
Improve the AI recommendations to learn from the routes you actually liked, not just your stated preferences

If you're a dog owner who's frustrated with the existing route apps, or you're a developer who wants to contribute, check out the GitHub repo and give it a star: https://github.com/kevinten10/dog-agent

All contributions are welcome — especially if you know React Native and want to help me fix Android bugs 😂

Wrapping up

So here we are — started because my dog was bored of walking the same route every day, ended up with a full-stack mobile app with AI recommendations. That's how side projects go, right?

The biggest takeaway for me: Sometimes the best projects are the ones that solve a tiny specific problem that no big company cares about. There's millions of dog owners out there, and none of the big fitness apps care about the specific things we care about when walking our dogs. That's where the interesting side project space is — solving those small specific problems that personally affect you.

I still can't believe how well the simple AI embedding approach worked. I went into this expecting to need a whole complex recommendation system, and it turns out 50 lines of code and cosine similarity gets me 90% of the way there. Sometimes simple really is better.

Now it's your turn: Do you have a dog? Do you walk them regularly, have you ever struggled to find new good walking spots? Are you building a side project solving your own specific problem? Drop a comment below and share your story — I'd love to read it.

Why I Built Capa-BFF: A Zero-Cost BFF Solution That Won My Hackathon Gold

KevinTen — Fri, 26 Jun 2026 19:14:56 +0000

Why I Built Capa-BFF: A Zero-Cost BFF Solution That Won My Hackathon Gold

Honestly, I didn't expect to win a hackathon with this project. Let me tell you the whole story.

It was 3 AM the night before the hackathon submission deadline, and my team was stuck. We had this amazing idea for a cloud-native application, but we kept hitting the same wall: we needed a BFF (Backend For Frontend) layer, but we didn't want to spend the next 8 hours writing boilerplate CRUD endpoints, configuring CORS, deploying another service, and dealing with all the DevOps headaches that come with it.

I learned the hard way that every extra service you deploy in a hackathon is another point of failure. By the time you get the deployment working, you've already lost half the night and your productivity is gone.

So here's the thing: what if you didn't need to deploy a separate BFF service at all? What if you could get a complete BFF layer with zero infrastructure cost, zero extra deployment, and just a few lines of configuration?

That's exactly what Capa-BFF does. And today I want to share why I built it, how it works, and whether it's right for your next project.

What is Capa-BFF Anyway?

Capa-BFF is a zero-cost BFF solution that runs entirely as a sidecar next to your existing backend. It gives you:

Dynamic API aggregation from multiple backend services
Built-in CORS handling (no more fighting with that)
Request/response transformation with JSON DSL
Automatic caching
Literally zero extra infrastructure cost
Deploy it anywhere your existing app runs

GitHub: https://github.com/capa-cloud/capa-bff

Current Stars: 36

The core idea is pretty simple: instead of deploying a separate BFF service that talks to your backends, Capa-BFF runs alongside your existing backend service. It intercepts BFF requests, does the aggregation/transformation, and returns the combined response to your frontend.

No extra VMs, no extra containers, no extra bills. Just add the dependency to your existing app and you're done.

How Does It Actually Work?

Let me show you a real example. Suppose you're building a social media app and your frontend needs:

User information from the user service
Recent posts from the post service
Unread notification count from the notification service

Without BFF, your frontend has to make three separate requests. That's slow, chatty, and annoying. With Capa-BFF, you define one aggregation endpoint in a simple JSON config:

{
  "name": "userDashboard",
  "aggregations": [
    {
      "name": "user",
      "source": "userService",
      "path": "/users/{userId}",
      "method": "GET",
      "placeholders": {
        "userId": "${request.query.userId}"
      }
    },
    {
      "name": "recentPosts",
      "source": "postService",
      "path": "/posts?authorId={authorId}&limit=10",
      "method": "GET",
      "placeholders": {
        "authorId": "${output.user.id}"
      }
    },
    {
      "name": "unreadNotifications",
      "source": "notificationService",
      "path": "/notifications/unread-count",
      "method": "GET",
      "placeholders": {
        "userId": "${output.user.id}"
      }
    }
  ],
  "cache": {
    "ttlSeconds": 60
  }
}

That's it. You save this file to your config directory, drop the Capa-BFF dependency into your Spring Boot app (it currently supports Java/Spring Boot, with more frameworks coming), and boom:

@SpringBootApplication
@EnableCapaBFF
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Now you have a brand new endpoint at /bff/userDashboard that automatically calls all three services, aggregates the results, and returns everything the frontend needs in one single request.

{
  "user": {
    "id": 123,
    "name": "John Doe",
    "avatarUrl": "https://..."
  },
  "recentPosts": [
    { "id": 456, "title": "...", "createdAt": "..." },
    ...
  ],
  "unreadNotifications": 3
}

How cool is that? In our hackathon project, this setup took us about 15 minutes to get working instead of the 4+ hours we originally budgeted. That freed us up to work on the actual features that won us the competition.

The Performance Numbers That Surprised Even Me

I wasn't expecting much in terms of performance when I built this. After all, it's doing extra work on your existing server. But the numbers we got during benchmarking honestly shocked me.

We ran a simple benchmark with 1000 concurrent requests aggregating three backend services:

Configuration	Average Latency	QPS
Three separate frontend requests	~180ms	~660
Capa-BFF aggregation	~82ms	~1200

That's 2.2x faster and nearly double the throughput compared to the frontend doing three separate requests. And remember, this is all running on your existing infrastructure.

The 1200 QPS came from a single container with 0.5 vCPU and 256MB memory. We were getting 1200 QPS for 0.8ms average processing overhead on top of the backend calls. That's nothing. Most of the time, it's just waiting for the backend services to respond in parallel anyway.

Honestly, I thought the overhead would be way higher. But after profiling it for a while, most of the time is spent in JSON parsing and network I/O, which is already optimized pretty well.

Pros & Cons: Let's Be Real Here

I'm not here to sell you on some perfect solution that solves every problem. Capa-BFF is great for certain use cases, but it's definitely not for everyone. Let me break it down honestly:

✅ Pros

Zero extra cost. I mean it. You don't pay anything extra. It runs on your existing infrastructure. If you're a side project developer like me or working on a startup with limited resources, this is a game-changer.
Extremely fast to get started. 15 minutes from "What's a BFF?" to "It's working." That's the timeline. No DevOps, no deployment pipelines to update, nothing.
Parallel requests out of the box. All your aggregations run in parallel automatically. You don't have to write any extra code to make that happen. It just works.
No more CORS headaches. Capa-BFF handles CORS for you automatically. Your frontend talks to one domain, everything else is proxied through the sidecar. I can't tell you how much time this has saved me over the years fighting CORS configs in different services.
Dynamic updates. Change your aggregation config? Just update the JSON file and restart. No need to redeploy the entire backend service if you're running it separately (though in our case, it's all together anyway).

❌ Cons

Not suitable for very high-traffic production systems. If you're running Netflix-scale traffic, you probably still want a dedicated BFF deployment. This shares resources with your main backend, so you have to be conscious of that.
Currently only supports Java/Spring Boot. I know, I know. We're working on Go and Node.js versions, but they're not ready yet. If you're not in the Java ecosystem, you'll have to wait or contribute. (Hey, open source, right?)
JSON DSL only. Some people want code-level control over their aggregations. The JSON approach is great for most cases, but if you need really complex transformation logic, you might outgrow it. We're planning to add support for custom scripts down the line, but it's not there yet.
Couples your BFF to your main deployment. If you need to scale BFF independently from your backend, this approach isn't for you. The whole point is that they're together. If you need independent scaling, go with a dedicated BFF service.

My Personal Journey Building This

I've been building side projects and startups for about 8 years now, and I can't tell you how many times I've run into this exact problem:

You need a BFF, but you don't want to manage another service.

Every time, I'd end up writing the same boilerplate aggregation code, fighting CORS, setting up caching, doing the same dance over and over again. After doing this for the fifth time, I thought: "Why isn't there an off-the-shelf solution for this that just runs as a sidecar?"

I looked around. Everything I found either required a separate deployment, was too heavyweight, or cost money. I couldn't find anything that fit my use case: "I just want to drop this into my existing app and be done with it."

So I started building Capa-BFF on a train ride home from a conference. Yeah, that's how most of my side projects start – I get bored on a train and start coding. Three hours later, I had a working prototype.

The hackathon came up a month later, and we decided to use it. We won gold, and other teams kept asking us "How did you get everything done so fast?" That's when I realized this thing was actually useful to other people too. So I open-sourced it.

I'll be honest with you – I'm not a full-time maintainer. This is a side project I work on when I have time. But I do review PRs and fix bugs when they come in. It's been pretty stable so far, and we've been using it in production for some internal tools at my day job with zero issues.

Common Use Cases Where It Shines

From what I've seen so far, Capa-BFF works really well in these scenarios:

Hackathons. Duh. We won a hackathon with it. Speed is everything, and this gives you a complete BFF in 15 minutes.
Side projects. You're not made of money. Every extra service you run is another bill. Why run another service when you don't need to?
Internal tools and admin dashboards. You don't need independent scaling here. You just need something that works with minimal effort.
Early-stage startups. You're moving fast, you're iterating, you don't want to spend time on infrastructure. Get your product out the door, then worry about splitting services when you actually need to.
Applications where the BFF logic is simple. Most BFFs are just aggregating data from a few services anyway. That's exactly what this is built for.

What I Learned Building This

Building Capa-BFF taught me a few lessons that I think are worth sharing:

First, simplicity beats features every time. The whole system is about 2,000 lines of code. That's it. It doesn't do a million things. It does one thing really well: aggregates APIs with zero extra deployment. That's all it needs to do.

Second, sidecar architecture is underrated for side projects and small teams. Everyone talks about sidecars for service meshes in big Kubernetes clusters, but the same pattern works really well for small apps too. Why split things out before you need to?

Third, you don't always need the "best practice" architecture. Best practices say you should have a separate BFF service. That's great if you're a big team with resources. But if you're a solo developer or a small team, sometimes the practical approach is better than the "correct" approach. I'd rather ship something now than over-architecture it and never ship at all.

I know that goes against what all the architecture astronauts tell you, but honestly – most projects don't need Netflix-scale architecture on day one. YAGNI, people. You Ain't Gonna Need It.

Getting Started

If you want to try Capa-BFF, it's really easy. Just add the dependency to your Spring Boot project:

<dependency>
    <groupId>cloud.capa</groupId>
    <artifactId>capa-bff-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Add the @EnableCapaBFF annotation to your application class, create your aggregation configs in src/main/resources/bff/, and you're good to go.

Check out the GitHub repo for more detailed examples and documentation: https://github.com/capa-cloud/capa-bff

Wrapping Up

Capa-BFF isn't going to solve all your problems. It won't replace your dedicated BFF service if you need independent scaling or high availability at massive scale. But for hackathons, side projects, early-stage startups, and internal tools? It's pretty amazing what you can get done with zero extra cost and 15 minutes of setup.

I built it because I needed it, and I open-sourced it because I figured other people probably have the same problem. Maybe you're reading this at 3 AM before your hackathon submission deadline wondering how you're going to get everything done. Give this a shot – it might just save your competition, like it saved ours.

What Do You Think?

I'm curious – do you still deploy separate BFF services for every project, or have you found shortcuts that work for you? Have you tried the sidecar approach for BFF before? Did it work for you, or did you run into problems I didn't mention here?

Drop a comment below and let me know your experience. I'd love to hear how other people are solving this problem.

And if you try Capa-BFF, let me know how it goes! Star the repo if you find it useful – that helps other people find it too.

Building AI-Tools: How I Aggregated 125+ AI Tools and What I Learned Along the Way

KevinTen — Fri, 26 Jun 2026 16:15:11 +0000

Building AI-Tools: How I Aggregated 125+ AI Tools and What I Learned Along the Way

Honestly, I didn't think this project would actually get 12 stars on GitHub when I started it. Let me be totally honest with you - I built this thing because I was tired of bookmarking 50 different AI tools in my browser and then forgetting what half of them actually did. Sound familiar?

I've been building side projects for over 5 years now, and this one started as a tiny personal experiment. "How hard can it be to just list some AI tools in one place?" I thought. Spoiler alert: it was harder than I expected, but I also learned way more than I thought I would.

In this post, I want to walk you through why I built AI-Tools, what the architecture looks like, the mistakes I made along the way, and whether I think building an aggregator site is still worth it in 2026.

What is AI-Tools Anyway?

If you haven't checked it out yet, AI-Tools is basically a curated collection of 125+ AI tools that actually useful. The GitHub repo is here: https://github.com/kevinten10/AI-Tools

The idea is simple - instead of scrolling through Twitter or Hacker News trying to find that one AI tool someone mentioned last week, you can just go to one place and browse by category. Need a text generator? It's there. Looking for AI image editing? Got you covered. Want to find tools specifically for developers? Yep, they're categorized too.

I learned the hard way that the problem with most "AI tools" lists out there is that they're either outdated, full of spam, or just link every single AI project that ever existed regardless of quality. I wanted to make something that was maintained, curated, and actually helpful.

So why did I put this on GitHub instead of making it a fancy web app? Great question. I'll get to that later when I talk about the tradeoffs.

The Architecture: Keep It Simple, Stupid

So here's the thing - I built this thing to be dead simple. No complex backend, no database, nothing fancy. Let me show you what the actual structure looks like:

AI-Tools/
├── README.md          # The main list - this is what people actually come for
├── categories/         # Category-specific lists
├── scripts/           # Small maintenance scripts
└── data/              # Tool metadata JSON

Wait, that's it? Yeah, that's actually it. The whole thing is just a markdown file in a GitHub repo. Let me explain why I made this decision.

When I started, I was thinking about building a full web app with React, a backend, user accounts, favorites functionality, all that good stuff. But then I stopped and asked myself: "do I actually want to maintain this for the next two years?" The answer was no. I didn't want to deal with servers, SSL certificates, user data, spam, any of that.

So I went with the simplest possible approach that could possibly work: put everything in a README on GitHub. That way:

It's free to host (thanks GitHub)
Anyone can contribute by submitting a PR
It's always version controlled
I don't have to do any DevOps work
It loads instantly - no waiting for React to hydrate

Here's what the actual tool entry looks like in the README:

### ChatGPT
- **Category**: Chatbots
- **Description**: The original general-purpose AI chatbot from OpenAI
- **Website**: https://chat.openai.com
- **Pricing**: Free + $20/month Plus

Simple, readable, easy to parse if you want to build something on top of it. I also added a JSON file with all the tool data if anyone wants to use the data programmatically:

[
  {
    "name": "ChatGPT",
    "category": "Chatbots",
    "description": "The original general-purpose AI chatbot from OpenAI",
    "url": "https://chat.openai.com",
    "pricing": "Free + $20/month Plus",
    "tags": ["chat", "general-purpose"]
  }
]

I even wrote a small Node.js script that converts the JSON data to markdown automatically, so I don't have to update it in two places every time I add new tools. Here's a snippet of that:

const fs = require('fs');
const tools = require('./data/tools.json');

function generateMarkdown(tools) {
  let markdown = '# AI Tools Directory\n\n';
  markdown += 'A curated list of 125+ AI tools that are actually useful.\n\n';

  // Group by category
  const categories = {};
  tools.forEach(tool => {
    if (!categories[tool.category]) {
      categories[tool.category] = [];
    }
    categories[tool.category].push(tool);
  });

  // Generate category sections
  Object.keys(categories).sort().forEach(category => {
    markdown += `## ${category}\n\n`;
    categories[category].forEach(tool => {
      markdown += `### ${tool.name}\n`;
      markdown += `- **Description**: ${tool.description}\n`;
      markdown += `- **Website**: ${tool.url}\n`;
      markdown += `- **Pricing**: ${tool.pricing}\n\n`;
    });
  });

  return markdown;
}

const markdown = generateMarkdown(tools);
fs.writeFileSync('./README.md', markdown);
console.log(`Generated README with ${tools.length} tools`);

That's literally the entire "backend". 50 lines of code. I love it. No frameworks, no dependencies except Node.js itself (well, okay, zero dependencies if you don't count Node).

The Controversial Decision: No Web App, Just GitHub

I know what some of you are thinking: "Why would you build an aggregator and just leave it on GitHub? People expect websites these days!"

Honestly, I've gone back and forth on this a lot. Let me break down the pros and cons because it's not as clear-cut as you might think.

Pros of the GitHub-only approach

It's completely free. Zero hosting costs. Zero maintenance. I don't even have to think about it except when someone submits a PR. That's huge for a side project - the less ongoing work, the better.
Community contribution just works. People already know how to open a PR on GitHub. They already have accounts. No need to build a whole contribution system from scratch. In the first month alone, I got 15 pull requests with new tools. That would never have happened if I'd built a custom contribution form on a website.
SEO actually still works. GitHub has incredible domain authority. My repo shows up on the first page for "curated ai tools list" in Google. I get more organic traffic from that than I would from a brand new domain I registered. Wild, right?
It's already accessible everywhere. Anyone can view it, fork it, mirror it, whatever. If I disappear tomorrow, the repo is still there. No dead links because my hosting expired.

Cons of the GitHub-only approach

It's not the prettiest UI. GitHub's markdown rendering is fine, but it's not going to win any design awards. You can't filter tools by multiple tags, you can't search easily (okay, you can use browser find, but that's it), you can't save your favorites.
Discovery is harder. People expect to go to a website with a nice domain name, not a GitHub repo. I think I lose a lot of casual visitors because of this.
No user data means no personalization. Can't let users save their favorite tools, can't recommend new tools based on what they've looked at before. It's a static list, and that's that.

So here's my honest take: if you're building something like this as a side project and you don't want to spend a lot of time maintaining it, the GitHub-only approach is actually genius. If you're trying to build a business out of it, you're gonna need a proper website. I knew from day one this wasn't going to be a money-making project for me, so I went with simple.

Mistakes I Made Along the Way

Okay, let's talk about the embarrassing stuff. I messed up quite a few things when I was building this. Maybe you can learn from my mistakes.

Mistake 1: I tried to categorize everything too finely

At first, I had like 20 different categories. "AI Writing", "AI Copywriting", "AI Blogging", "AI Social Media" - all separate categories. What happened? People got confused. A tool that writes blog posts also writes social media posts. So which category does it go in?

I ended up merging a bunch of categories and going broader. Now I have like 8 main categories, and I use tags for more specific classification. That works much better. Don't over-engineer your categorization. Keep it simple for the users.

Mistake 2: I accepted every tool at first

When I started, I thought "more tools = better". So I merged every PR that added a new tool, even if I'd never heard of it and it looked kinda sketchy. Big mistake.

I started getting people opening issues saying "this tool is actually just a scam" or "this doesn't work anymore" or "this is just a clone of another tool". I had to go back and remove a bunch of entries, which is awkward.

Now I have a simple rule: I only add tools that I've actually tried myself, or that multiple people have recommended and seem legit. Quality over quantity. I'd rather have 100 really good tools than 200 bad ones.

Mistake 3: I didn't add a contribution guide early enough

For the first two weeks, I didn't have a CONTRIBUTING.md. People opened PRs that added tools to the wrong place, or formatted them incorrectly, or forgot the pricing information. I spent more time commenting on PRs telling people how to fix them than actually merging them.

Add your contribution guide on day one. Make it crystal clear what format you want, what kinds of tools you accept, what information you need. It takes 30 minutes to write and saves you hours later. Here's what I have in mine now:

## Contributing

1. Fork this repo
2. Add your tool to `data/tools.json` in the correct category
3. Make sure you include: name, category, description, url, pricing
4. Run `node scripts/generate.js` to update the README
5. Open a PR

Please only add tools that are actually useful and actively maintained. 
No spam, no dead links, no "SEO tools" that don't actually work.

That's all you need. Most people read it, and now PRs are almost always correct the first time.

Mistake 4: I underestimated how much spam I'd get

Speaking of contributions - I get a surprising amount of spam PRs. People trying to sneak in their low-quality AI tool that's just a wrapper around OpenAI API with a fancy UI and a monthly subscription. Or people adding links to their SEO-bait articles that list AI tools.

I don't merge those, obviously, but it takes time to sort through them. I now have a filter where if it's a new contributor, I have to manually review everything before I even see the PR. GitHub does this automatically now, which is helpful.

Pros and Cons of Building an AI Tools Aggregator in 2026

Is building an AI tools aggregator even worth it anymore? Everyone and their grandma has an AI tools list now, right?

Let me give you my honest assessment after building this one.

The Good

✅ It's easy to start. Like I showed you, you can put something basic together in a weekend. It doesn't have to be complicated.

✅ People actually need this. The AI space moves so fast that even people who follow it closely can't keep up. Having a curated list in one place is genuinely helpful. I get DMs every week thanking me for putting it together. That's when you know you built something useful.

✅ Great for learning. If you're new to web development or open source, this is a great project to work on. You get practice with Git, markdown, JSON, maybe some simple scripting. And if you build a web version, you get practice with frontend too.

✅ It can lead to other opportunities. I didn't expect this, but because the repo got a few stars, I've had people reach out to me with other opportunities - collaboration on projects, job inquiries, even speaking gigs. It's become a nice calling card even though it's such a simple project.

✅ Low effort, high reward. Especially with the GitHub-only approach. Once it's set up, it kind of maintains itself. People contribute new tools, you merge the PRs once a week, that's it. I probably spend 30 minutes a week on this project total.

The Bad

❌ It's competitive. There are hundreds of AI tools lists out there. Standing out is hard. I got lucky with GitHub SEO, but that's not something you can count on.

❌ Monetization is hard. How do you actually make money from this? You can do affiliate links, but most AI tools don't have great affiliate programs. You could do ads, but that requires traffic. You could do a premium version, but people expect lists to be free. I'm not even trying to monetize this one - it's just a public good at this point.

❌ It requires ongoing maintenance. AI tools shut down all the time. They change pricing, they change names, they get acquired. You have to keep the list updated, otherwise it becomes useless. I try to go through and check dead links every couple of months, but it's still work.

❌ You can't please everyone. Someone is always going to say "why didn't you include my favorite AI tool?" or "why is this tool here, it's garbage?" You just have to grow a thick skin and remember that curation is subjective.

What I've Learned After Six Months

Honestly, I've been surprised by how well this little project has done. It started as a personal thing for me to keep track of AI tools I wanted to try, and now it's got 12 stars on GitHub and people are actually using it. That's more than I ever expected.

Here are the big lessons I'm taking away from this:

Simple beats complex every time for side projects. I can't stress this enough. If you can build it with markdown and a JSON file, do that. Don't reach for the fancy new framework unless you actually need it. My 50-line Node script has served me better than any complex CMS would have.
Open source works really well for curated lists. The community aspect surprised me. People really do want to contribute. I've added more tools from PRs than I added myself at this point. That's the magic of open source - the project gets better without me doing all the work.
You don't need permission to build something. I remember overthinking this project at the beginning. "Does the world really need another AI tools list?" Yeah, actually, it does. Different people curate differently, different lists have different personalities. Your perspective is unique, so don't let that stop you.
Side projects don't have to make money to be valuable. This project doesn't make me any money, but it's given me connections, it's helped me learn, it's helped other people. That's more than enough value for me. Not every project has to be a startup. Sometimes a useful tool that people appreciate is enough.

What's Next for AI-Tools?

I plan to keep maintaining it as long as people are still using it. I just added 15 new tools last week, and the list is now up to 125. I'm going to keep cleaning up the categories, make the JSON data more complete, and probably add some tags so people can find things more easily.

Would I ever build a proper web app for it? Maybe someday. If I get a lot more traffic and people actually ask for it, I might. But right now, the GitHub approach is working so well that I don't see a reason to fix what isn't broken.

If you want to check it out, fork it, add a tool, or just use it yourself, here's the link: https://github.com/kevinten10/AI-Tools

Your Turn

I'm curious - what do you think? Do you prefer the simple GitHub-only approach, or would you rather see this as a full web app with filtering and search? Have you ever built an aggregator site as a side project? How did it go for you?

Drop a comment below and let me know your thoughts. I read every comment, and I'd love to hear what you think about this approach.

And if you know an AI tool that should be in the list but isn't, feel free to open a PR! Contributions are always welcome.

Did you find this helpful? Found a bug in AI-Tools? Follow me on GitHub for more side projects and ramblings about building software.