DEV Community: KevinTen

OpenOctopus: Realm-Native AI Life Assistant System With Summon Technology

KevinTen — Wed, 29 Jul 2026 01:25:10 +0000

OpenOctopus: Realm-Native AI Life Assistant System With Summon Technology

Overview

OpenOctopus is an open source project hosted on GitHub. According to its repository documentation, the project is positioned as an "AI family home hub" with the guiding principle: "One event, every member, the right context." The project is released under the MIT license.

As described in the README, OpenOctopus distinguishes itself from traditional unified chatbox designs by framing itself as "a family member in the group chat." The system organizes family life into "Realms" — pet, parents, finance, work, health — each with its own knowledge base, agent team, and skill set. The project documentation uses an octopus as its central metaphor: each tentacle has its own nerve center and acts autonomously, while a central brain coordinates everything.

Core Features

The documentation outlines OpenOctopus's key functional modules:

Realm Matrix — A grid dashboard providing at-a-glance visibility into health scores, risks, and to-dos across all life realms
Summon — Transforms any entity (pet, person, asset) into an AI agent with memory, personality, and proactive behavior
Cross-Realm Intelligence — A knowledge graph connecting entities across all realms (your pet realm knows your finance budget)
Dual-layer Skills — Global skills (search, calendar, email) plus realm-specific skills (vet lookup, tax calculation, law search)
Agent Teams — Professional agents and summoned agents collaborate within each realm
RealmHub — One-click installation of pre-built realm packages
Governance — Human-in-the-loop approval, full audit log, privacy and permission tiers
Local-first — SQLite by default, with optional cloud sync via PostgreSQL or Supabase

The Realm Matrix

The documentation defines these pre-configured realm templates. Users can freely create, merge, or delete realms:

Realm	Contents	Example Agents
`pet`	Pets, vets, food records	Health advisor, Momo (summoned)
`parents`	Parents, health files	Care assistant, Mom (summoned)
`partner`	Partner, anniversaries	Relationship advisor
`finance`	Accounts, investments, debts	Budget planner, tax assistant
`work`	Projects, colleagues, goals	Task manager, weekly reporter
`legal`	Contracts, cases, statutes	Contract lawyer, labor law advisor
`vehicle`	Car, insurance, maintenance	Maintenance tracker, cost reporter
`home`	House, appliances, repairs	Home manager
`health`	Check-ups, prescriptions	Health monitor
`fitness`	Training plans, body data	Fitness coach
`hobby`	Projects, learning materials	Learning coach
`friends`	Social circle, events	Social radar

The Summon Mechanism

The documentation describes Summon as the "killer feature" that turns data into a living agent.

The transformation pipeline:

Raw data → Structured Entity → SUMMON → Agent with memory, personality & initiative

Supported entity types:

Living — Pet, family, friend: Enables simulated dialogue, personality, and emotional expression
Asset — Car, house, portfolio: Enables status monitoring, maintenance alerts, and cost reporting
Organization — Company, hospital: Provides process guides and contact management
Abstract — Goal, project, habit: Enables progress tracking, deviation alerts, and retrospectives

The documentation includes this interaction example illustrating how summoned agents collaborate:

You:  "I'm traveling for 5 days next week."

Momo (Pet):     "Who's going to feed me and walk me for 5 days?!"
Mom (Parents):  "Mom just said she'd like to visit — she could take care of Momo."
Car (Vehicle):  "Charge to full before departure? Or take a taxi to the airport?"
Budget (Finance): "Trip budget estimate: ¥X. Remember to save receipts."

→ System compiles a "Trip Prep Checklist" for your approval.

Agent Team Architecture

The documentation defines a three-layer agent architecture:

Central Agents (global layer)

Router — Intent detection and realm routing
Coordinator — Cross-realm analysis
Scheduler — Proactive triggers and cron jobs

Realm Agents (per-realm layer)

Professional — Specialized roles like legal advisor, budget planner, health monitor
Summoned ✦ — Digitized entities like Momo, Mom, or a Tesla

RealmHub Ecosystem

RealmHub is described as "like an app store, but for life domains." Users can install complete realm packages such as:

Legal Advisor Team — Entity templates (lawyer, contract, statute) + 3 agents + skills
Pet Care — Pet profile + health advisor + vet lookup + vaccination tracker
Family Finance — Accounts + budget planner + investment analyzer

Each package includes: realm template, entity templates, agent configurations, skill configurations, and sample data.

High-Level Architecture

The documentation provides this architectural diagram:

  CLI / Web Dashboard / Mobile
               │
               ▼
┌──────────────────────────────────────────────┐
│            OpenOctopus Core (Brain)           │
│                                              │
│  Router Agent · Coordinator · Scheduler      │
│  Knowledge Graph (cross-realm entity links)  │
│  Global Skills (search·calendar·email·i18n)  │
└──────┬──────────┬──────────┬──────────┬──────┘
       │          │          │          │
  ┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌───▼────┐
  │  Pet   │ │Finance │ │ Legal  │ │Parents │  ...
  │ Realm  │ │ Realm  │ │ Realm  │ │ Realm  │
  │        │ │        │ │        │ │        │
  │ Agents │ │ Agents │ │ Agents │ │ Agents │
  │ Skills │ │ Skills │ │ Skills │ │ Skills │
  │ Memory │ │ Memory │ │ Memory │ │ Memory │
  └────────┘ └────────┘ └────────┘ └────────┘

  ✦ Summoned agents live inside their realm.
  ↔ Knowledge graph links entities across realms.

Governance Model

Every agent action follows a documented trust chain:

Human-in-the-loop — Critical actions require explicit approval
Audit log — Full trace of every agent decision, evidence, and outcome
Privacy tiers — Per-realm permission control with data isolation between realms
Budget limits — Token and cost caps per agent, per realm, per action

Technology Stack

Based on the Dockerfile and package.json, the project's technical choices are:

Layer	Selection
Runtime	Node.js >= 22 + TypeScript
Gateway	Unified orchestration (ref: OpenClaw Gateway)
Client	Web Dashboard (Realm Matrix) + CLI (`tentacle`)
Data	SQLite (local-first) + PostgreSQL / Supabase (optional sync)
Vector	pgvector / local vector store (per-realm sharding)
Plugin	Global Skill + Realm Skill + Realm Package spec

The project uses pnpm as its package manager (version 10.30.2). CI/CD is managed through GitHub Actions.

The project supports multiple LLM providers. The documentation specifically mentions configuration for the Volcengine Ark Agent Plan, requiring ARK_API_KEY, ARK_BASE_URL, and ARK_CHAT_MODEL environment variables.

Ecosystem Components

The documentation defines the project's ecosystem naming conventions:

Realm marketplace: RealmHub
CLI: tentacle (Tentacle = reach & touch)
Agent gateway: ink (Ink = information flow)
Summon engine: summon
Community: The Reef (Coral reef = habitat)
Realm config: REALM.md
Entity persona: SOUL.md

Project Mascot

The project mascot is a deep-sea octopus named Octo. The documentation describes Octo as "calm, multi-threaded, quietly brilliant." Eight arms juggle your entire life while one brain keeps it all in sync. The tentacle tips glow cyan when summoning entities to life.

Interpretation and Discussion

The content above is based entirely on the project's public README documentation and configuration files found in the code repository. All feature descriptions reflect design goals and specifications documented in the repository.

This project's architecture presents an innovative approach to family AI assistants. Whereas traditional AI assistants typically provide a unified conversational interface, OpenOctopus's "multi-realm + multi-agent" paradigm attempts to provide more granular context management and role specialization. The Summon mechanism is an intriguing conceptual exploration that seeks to digitize real-world entities as agents and enable multi-agent collaboration.

For developers researching agent architectures, family AI applications, or multi-agent systems, this project's code and documentation may serve as a useful reference. The project is open source, and interested readers can examine the code repository to understand the implementation details.

Sources

Project repository: https://github.com/open-octopus/openoctopus
Referenced commit: https://github.com/open-octopus/openoctopus/commit/67ac1f92f99ea8285dcf6e14c06077681376a885

ccuse: A Profile Switcher for Claude Code CLI

KevinTen — Mon, 27 Jul 2026 16:00:33 +0000

ccuse: A Profile Switcher for Claude Code CLI

This repository contains ccuse, a command-line profile switcher designed for the Claude Code CLI. The tool enables developers to switch between native Claude Code account/subscription mode and compatible API providers across three configuration scopes: globally, per project, or for a single temporary shell session.

What ccuse Provides

According to the repository documentation, ccuse addresses a specific need for developers using Claude Code with multiple AI API providers. Instead of manually editing configuration files or managing multiple sets of environment variables each time you want to use a different model provider, ccuse creates, stores, and activates profiles through simple shell commands.

The documented functionality supports five API provider profiles:

Claude (Native) - Uses the Claude Code account/subscription or Anthropic API directly
Volcengine Ark - Uses the Volcengine Ark Agent Plan
GLM via Ark Agent Plan - Uses GLM models through the Volcengine Ark Agent Plan
Kimi - Uses Moonshot AI's Kimi API
MiniMax - Uses the MiniMax API

Each profile corresponds to specific models. For example, the Volcengine Ark profile supports doubao-seed-2-0-code-preview-260215, GLM profiles support GLM-5.1, GLM-4.7, and GLM-4.7-FlashX, Kimi profiles support kimi-k2.6, and MiniMax profiles support MiniMax-M2.7 and MiniMax-M2.7-highspeed. Context windows for these models range up to 256K, based on each provider's documented specifications.

Three Configuration Scopes

One of the key design features described in the documentation is the ability to apply profiles at three different scopes, each with different persistence characteristics.

Global Scope

Global profile switching modifies the main Claude Code settings.json file. When activated, the selected profile becomes the default for all Claude Code instances launched anywhere on the system. The tool automatically creates a backup of the current settings file before switching profiles.

Commands at this scope include:

ccuse claude or ccuse global claude - Switch to native Claude profile
ccuse ark or ccuse global ark - Switch to Volcengine Ark profile
ccuse glm or ccuse global glm - Switch to GLM profile
ccuse kimi or ccuse global kimi - Switch to Kimi profile
ccuse minimax or ccuse global minimax - Switch to MiniMax profile

Project Scope

Project-scoped profiles allow a specific repository or working directory to use a different provider than the global default. This is useful when working on multiple projects that have different model requirements or when you want to isolate testing of a particular provider without affecting your global default configuration.

Project scope creates a ./.claude/settings.json file in the current working directory, leaving the global ~/.claude/settings.json file untouched. Claude Code automatically reads project-level configuration when launched from that directory.

Commands include:

ccuse project <profile> - Persist profile for current project
ccuse project show - Display current project profile
ccuse project rm - Remove project-specific profile

Session Scope

Session-level switching operates entirely through environment variables and makes no permanent file changes. This is useful for one-off testing or when you want to temporarily try a different provider without changing any persistent configuration.

When using eval "$(ccuse local <profile>)", the profile's environment variables are loaded into the current shell session. The ccuse start <profile> command loads the environment variables and immediately launches Claude Code.

Quick-start shortcuts are also provided:

ccuse cc - Claude profile + launch
ccuse ca - Ark profile + launch
ccuse ck - Kimi profile + launch
ccuse cg - GLM profile + launch
ccuse cm - MiniMax profile + launch

The -c or --continue flag can be added to resume the last Claude Code conversation.

Profile Management Features

Beyond switching profiles, the tool includes several profile management commands:

ccuse init-<provider> - Creates or reconfigures a profile template
ccuse list - Lists all available profiles and marks the active one
ccuse show - Shows current Claude Code configuration with secrets masked
ccuse doctor - Checks setup, active scopes, and suggests next steps
ccuse edit <name> - Opens a profile file for editing
ccuse remove <name> - Removes a profile after confirmation

The ccuse doctor command is described as particularly useful for first-time users or when troubleshooting, as it checks whether Claude Code, Python, profiles, and project settings are properly configured.

Installation Methods

Three installation approaches are documented:

One-Line Install (Recommended): Downloads the script directly to ~/.local/bin/ccuse and makes it executable
Install via Claude Code Skill: Can be installed by asking Claude Code directly
Manual Install: Involves cloning the repository and creating a symlink to the executable

After installation, ccuse --help verifies that the tool is working correctly.

Profile Setup Workflow

The documented workflow for setting up profiles follows five steps:

Check setup with ccuse doctor to verify prerequisites
Save current Claude settings with ccuse init-claude to create a native Claude profile
Create additional profiles using commands like ccuse init-ark, ccuse init-glm, ccuse init-kimi, or ccuse init-minimax
Set API keys by editing the profile files that are automatically opened
Choose the scope for each profile: one-time session, project-specific, or global

When creating profiles, the init commands automatically open the profile file for editing using the user's preferred editor (following the order: $EDITOR environment variable, VS Code code, then nano).

Custom Profiles

The documentation indicates that developers can create custom profiles for any Anthropic-compatible API. Custom profiles are stored as JSON files in ~/.claude/profiles/ and can contain configuration for API keys, base URLs, timeout settings, and other environment variables.

Profile naming rules are specified: names must start with a letter or number and may contain letters, numbers, dots, underscores, and hyphens. Certain names are reserved and cannot be used for custom profiles, including built-in commands and aliases.

File Structure

The tool stores profiles and configuration in the following directory structure under ~/.claude/:

settings.json - Active global configuration
settings.json.bak - Automatic backup
profiles/ - Directory containing individual profile JSON files

Several environment variables are available to customize these paths, including CLAUDE_DIR, PROFILE_DIR, SETTINGS_FILE, BACKUP_SUFFIX, PROJECT_CLAUDE_DIR, and PROJECT_SETTINGS_FILE.

Testing

The repository includes a comprehensive test suite using bats-core (Bash Automated Testing System). Tests can be run after installing bats with bats tests/test_ccuse.bats.

Interpretation and Use Cases

Based on the documented functionality, this tool appears most useful for developers who regularly use Claude Code and want to experiment with multiple AI API providers without manual configuration overhead. The three scopes (global, project, session) provide flexibility matching different workflows.

Developers working across multiple projects with different model requirements may find the project-scoped profiles particularly useful, allowing each repository to maintain its own default provider without affecting the global configuration. Similarly, the session-level switching is well-suited for side-by-side testing of different providers on the same tasks.

The ability to create custom profiles also means the tool is not limited to the five pre-configured providers, potentially extending its utility to any API endpoint with Anthropic-compatible authentication.

Sources

Repository: https://github.com/kevinten-ai/ccuse
Verified commit: https://github.com/kevinten-ai/ccuse/commit/07adde051c787b6e3bb3585ace9a2a6080ebd7f9

Turning 125 AI Tools into a Practical Open Source Handbook

KevinTen — Mon, 27 Jul 2026 02:10:13 +0000

Turning 125 AI Tools into a Practical Open Source Handbook

AI tool lists are easy to start and hard to keep useful. Models, pricing, quotas, regional availability, and product status change constantly. A page that only collects links can become stale before readers make a decision.

The open source AI Tools Handbook takes a more structured approach. Its current catalog contains 125 tools across seven categories: AI development environments, command-line tools, models, multimodal tools, agents, MCP tools, and AI skills. The project combines browsing and filtering with SWOT notes, five-axis radar scores, workflow guides, and side-by-side comparisons for up to four tools.

What changed in the latest refresh

The July refresh focused on four practical areas:

Clearer information architecture. The landing page, tool details, comparisons, workflows, and subscription-oriented views now form a more deliberate path instead of one long catalog.
More reliable assets. Tool logos are maintained as local project assets, reducing broken cards caused by external image URLs.
Stronger responsive and accessible behavior. Navigation, focus states, semantic structure, and small-screen layouts received dedicated work.
Verifiable generated data. Catalog indexes are generated by scripts and checked before builds, which helps prevent displayed counts from drifting away from source data.

Why comparisons matter more than a universal ranking

There is rarely one best AI tool for every situation. A strong code completion product may not be the best choice for repository-wide refactoring. A capable model may still be a poor fit because of pricing, privacy requirements, or regional availability.

The handbook therefore keeps several dimensions visible instead of reducing every tool to one score. Readers can compare functionality, performance, usability, ecosystem, and value, then open the detailed notes for strengths, weaknesses, opportunities, and risks.

Six workflow templates add another layer of context by connecting tools to concrete development, research, and content workflows. Optional community features, including ratings, comments, and Battle voting, use Supabase. When Supabase is not configured, those community features are hidden while the core catalog continues to work.

Implementation

The frontend uses Vue 3, Vite 8, Tailwind CSS, Pinia, and Vue Router. The repository includes local development, production build, test, Docker, and PWA support. A contributor can add or update tool data through the documented schema and then run the catalog validation before submitting a change.

An important limitation

This is not a real-time pricing database. The repository explicitly warns that unverified pricing, model, quota, and product-status details should be treated as pending verification. The number 125 is a current repository snapshot, not a permanent promise.

That boundary is useful. It separates durable comparison structure from facts that must be checked against official product documentation before a purchasing or architecture decision.

Try the live handbook: https://aitools.rxcloud.group/

Explore the source: https://github.com/ava-agent/ai-tools

The project welcomes issues and pull requests for missing tools, stale details, and better comparison criteria.

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!