DEV Community: Capoerus

Beyond `json.encode()`: Building a Type-Aware JSON Conversion Layer in Dart

Capoerus — Mon, 12 Oct 2026 15:19:48 +0000

Reliable data serialization is one of those architectural concerns that often looks simple until an application grows.

At first, converting a Dart object into JSON and decoding it back seems straightforward. Dart already provides a native JSON implementation, and for many applications, it is more than enough.

The challenge begins when an application needs consistent type handling, custom object transformations, database-specific data formats, and predictable behavior across multiple platforms without introducing additional dependencies.

This is one of the problems I addressed while developing convert_json, an internal Dart package built for the Capoerus ecosystem.

Repository: https://github.com/Suebersson/convert_json

The architectural problem: JSON is not the same as a Dart object

JSON supports a limited set of data types: strings, numbers, booleans, null values, arrays, and objects.

Dart applications work with a much broader set of types, including DateTime, RegExp, enums, and custom classes.

The distinction becomes important when data crosses architectural boundaries.

Consider this JSON:

{
  "active": "true",
  "quantity": "100",
  "price": "19.95",
  "createdAt": "2026-10-12T15:30:00.000Z"
}

A standard JSON decoder preserves the quoted values as strings. It cannot automatically know that "true" represents a boolean, "100" represents an integer, or the date string should become a DateTime.

This is not necessarily a problem with Dart's JSON implementation. It is a consequence of JSON not preserving the original application's type information.

However, when different parts of an ecosystem repeatedly implement their own conversion rules, maintaining consistent behavior becomes more difficult.

I wanted a small, dependency-free conversion layer that could centralize these decisions while remaining flexible enough to accommodate application-specific requirements.

Why I built `convert_json`

The package has one responsibility: encode Dart data into JSON and decode JSON into Dart data, with configurable object transformations.

It is written entirely in Dart and does not depend on third-party packages.

The package is maintained in a private-by-design development workflow, with its source available in my GitHub repository. I do not intend to publish it on pub.dev.

This is a deliberate architectural decision. I want the implementation to remain directly available to me and to Capoerus, allowing rapid changes, adjustments, and updates as the ecosystem evolves.

The goal is not to create another general-purpose serialization framework. It is to maintain a focused, reusable component whose behavior I can control.

Recognizing primitive types during decoding

One of the package's features is its ability to recognize certain primitive types represented as strings.

The decoder uses regular expressions to identify potential integers, doubles, booleans, and date-time values before attempting their conversion.

For example, the integer pattern is:

static final RegExp intPattern = RegExp(r'^(-|)[0-9]{1,}$');

The corresponding boolean pattern is:

static final RegExp boolPattern = RegExp(
  r'^(true|false)$',
  caseSensitive: false,
);

The decoder then applies the appropriate conversion:

if (isString && datePattern.hasMatch(value)) {
  return DateTime.tryParse(value) ?? value;
} else if (isString && boolPattern.hasMatch(value)) {
  return bool.tryParse(value, caseSensitive: false) ?? value;
} else if (isString && intPattern.hasMatch(value)) {
  return int.tryParse(value) ?? value;
} else if (isString && doublePattern.hasMatch(value)) {
  return double.tryParse(value) ?? value;
} else {
  return value;
}

This allows matching values to be converted into their corresponding Dart types.

For example:

Input string	Resulting Dart type
`"true"`	`bool`
`"100"`	`int`
`"19.95"`	`double`
`"2026-10-12T15:30:00.000Z"`	`DateTime`, if accepted by the date pattern and parser
`"hello"`	`String`

The distinction is useful when working with data that has passed through a system that represents values differently from the original application.

There is an important caveat: type inference based on string content is a policy, not a universal truth. A string containing "100" might be an identifier rather than an integer. Applications must decide where this conversion is appropriate and where strings must remain unchanged.

That is why the package also supports explicit transformations.

`ObjectTreatment`: a controlled extension point

The ObjectTreatment abstraction allows an application to define how particular objects should be processed.

Instead of embedding every possible conversion rule in the package itself, the application provides a list of conditions and transformations.

Conceptually, each treatment contains two callbacks:

test: determines whether the object matches a particular rule.
treat: transforms the matching object into a JSON-compatible representation or another desired Dart value.

The decoding implementation checks these treatments before attempting primitive conversions:

if (treatments is List<ObjectTreatment> &&
    treatments.isNotEmpty) {
  for (final ObjectTreatment treatment in treatments) {
    if (treatment.test.call(value)) {
      return treatment.treat.call(value);
    }
  }
}

The first matching treatment takes precedence.

This design separates the conversion mechanism from the application's data policies. The package does not need to understand every database format, domain model, or external API. The application supplies the rules that matter to its own architecture.

The same concept is available during encoding, allowing custom objects to be transformed before the native JSON encoder processes them.

A production example: adapting Dart objects to MongoDB Extended JSON

In Capoerus, one practical use case involves adapting Dart objects to representations supported by MongoDB's Extended JSON conventions.

Two examples are DateTime and RegExp.

1. Encoding `DateTime`

A Dart DateTime object needs an explicit representation if the receiving system is expected to interpret it as a database date rather than an ordinary string.

The application defines a treatment that converts the date to UTC and produces a MongoDB-style date document:

ObjectTreatment(
  test: (object) => object is DateTime,
  treat: (object) {
    object as DateTime;

    object = object.toUtc();

    String iso8601 = object.toIso8601String();

    final int millisecond = object.millisecond;
    String millisecondTxt = millisecond.toString();

    if (millisecondTxt.length > 3) {
      millisecondTxt = millisecondTxt.substring(0, 3);
    }

    iso8601 = iso8601.replaceFirst(
      millisecondPattern,
      '.${millisecondTxt}Z',
    );

    return {'\$date': iso8601};
  },
)

The resulting representation follows the general shape:

{
  "$date": "2026-10-12T15:30:00.123Z"
}

The treatment makes the timezone and millisecond formatting explicit instead of leaving those decisions scattered across the application.

MongoDB supports several Extended JSON representations, so the exact format should match the interface being used. This example is intended for a compatible date representation, not as a claim that every MongoDB endpoint accepts every Extended JSON variant.

2. Encoding `RegExp`

Regular expressions introduce a different challenge: the pattern itself is not enough. Relevant flags may also need to be preserved.

The Capoerus implementation transforms a Dart regular expression into a document containing $regex and, when applicable, $options:

ObjectTreatment(
  test: (object) => object is RegExp,
  treat: (object) {
    object as RegExp;

    final Map<String, String> regex = {
      '\$regex': object.pattern,
    };

    if (object.isDotAll) {
      regex.update(
        '\$options',
        (options) => options += 's',
        ifAbsent: () => 's',
      );
    }

    if (!object.isCaseSensitive) {
      regex.update(
        '\$options',
        (options) => options += 'i',
        ifAbsent: () => 'i',
      );
    }

    if (object.isMultiLine) {
      regex.update(
        '\$options',
        (options) => options += 'm',
        ifAbsent: () => 'm',
      );
    }

    if (object.isUnicode) {
      regex.update(
        '\$options',
        (options) => options += 'u',
        ifAbsent: () => 'u',
      );
    }

    return regex;
  },
)

This allows the application to preserve selected regular-expression properties when converting the object into a database-compatible representation.

It also illustrates why a generic JSON encoder alone is not always sufficient for application architecture: the transformation may depend on the expectations of the receiving system.

Keeping the database adaptation outside the core package

The conversion package is intentionally independent of MongoDB.

The database-specific logic belongs to the Capoerus application layer, where the required format and integration behavior are known.

The application's Json class provides a convenient interface around the package:

import 'dart:typed_data' show Uint8List;
import 'package:convert_json/convert_json.dart';

final class Json {
  const Json(this.encoded);

  factory Json.emptyMap() => const Json('{}');

  factory Json.emptyList() => const Json('[]');

  factory Json.fromList(List<dynamic> data) {
    return Json(ConvertJson.encode(data));
  }

  factory Json.fromMap(Map<String, dynamic> data) {
    return Json(ConvertJson.encode(data));
  }

  final String encoded;

  dynamic get decoded => ConvertJson.decode(encoded);

  static String encode(Object codable) {
    return ConvertJson.encode(
      codable,
      treatments: treatmentsForEncoding,
    );
  }
}

The complete production implementation also includes database-specific formatting and decoding helpers, UTF-8 byte conversion, and immutable treatment configuration.

This separation has an architectural advantage: the package remains focused on conversion, while the application controls how data is prepared for a particular backend.

It also makes it possible to change database formatting rules without turning the general-purpose conversion layer into a database-specific library.

Supporting the reverse transformation

Serialization is only half of the problem. An application must also decide how to interpret the data it receives.

The Capoerus implementation includes a preprocessing function that recognizes selected MongoDB-style representations before passing the resulting JSON to the decoder.

For example, a date expressed in milliseconds since the Unix epoch can be converted into an ISO 8601 string:

encoded = encoded.replaceAllMapped(
  dateMillisecondsSinceEpochPattern,
  (match) {
    final String data = match.group(0) ?? '';
    final String dateTxt =
        digitsOnlyPattern.stringMatch(data) ?? '';

    final int dateEpoch = int.tryParse(dateTxt) ?? 0;

    final DateTime date =
        DateTime.fromMillisecondsSinceEpoch(dateEpoch).toUtc();

    return '"${date.toIso8601String()}"';
  },
);

Once the preprocessing is complete, the decoder can recognize the resulting date string and attempt to create a Dart DateTime.

This is an example of a two-stage conversion pipeline:

Normalize the external representation into ordinary JSON-compatible values.
Decode those values into Dart objects using the configured conversion rules.

The same general approach can be used for other database-specific structures, provided that the transformation is appropriate for the data format being received.

Encoding custom application objects

The package also supports transformations during encoding, including objects that implement a ToJson interface.

A simplified view of the encoder's fallback behavior looks like this:

if (object is Enum) {
  return object.toString();
} else if (object is DateTime) {
  return object.toIso8601String();
} else if (object is ToJson) {
  return object.codable;
} else {
  throw ConvertJsonException(
    'Unsupported object type: ${object.runtimeType}',
  );
}

The actual implementation also checks user-defined ObjectTreatment rules before these fallback cases.

This gives application developers several options:

Use the native JSON-compatible types.
Define custom treatments for specific objects.
Represent domain objects through ToJson.
Reject unsupported object types rather than silently assuming they can be serialized.

The last point is especially important. Explicit failure can make architectural problems easier to identify than implicit conversions that produce unexpected representations.

Of course, throwing an exception does not eliminate the need for error handling. Callers must still decide how conversion failures should be reported, logged, or handled.

Why keep the package private instead of publishing it on pub.dev?

Not every useful software component needs to become a public package.

For Capoerus, convert_json is an internal technology intended to support the ecosystem's implementation requirements.

Keeping it unpublished on pub.dev allows me to prioritize the needs of the application rather than maintaining a public release cycle or promising compatibility guarantees to external consumers.

The GitHub repository provides a place to maintain the source and track changes:

https://github.com/Suebersson/convert_json

This approach is particularly useful when the same conversion rules need to evolve alongside the rest of the application.

It does not mean that private packages are inherently more secure or reliable than public packages. Those properties depend on implementation quality, testing, maintenance, and the way the software is used.

The benefit here is control over the component's scope and evolution.

Pure Dart, without third-party dependencies

convert_json uses Dart's native JSON facilities and adds its own conversion logic on top.

It is intended for use across the following platforms:

Android
iOS
Linux
macOS
Web
Windows

Because the package does not depend on third-party packages, it avoids introducing additional package-level dependencies into the projects that consume it.

That does not automatically make the implementation secure, faster, or more reliable. Those qualities still need to be established through testing and appropriate error handling.

What it does provide is a smaller dependency surface and a conversion layer whose behavior is under direct control.

The package's scope is also deliberately limited. It is not intended to replace Dart's JSON implementation, provide a complete object-relational mapping system, or guarantee compatibility with every external data format.

It provides a configurable layer for encoding and decoding data, with additional transformations where the application needs them.

What I consider important in a conversion layer

When working on an application that spans mobile clients, web interfaces, and server-side components, I find it useful to make data-conversion rules explicit and reusable.

A conversion layer should have a clearly defined responsibility, predictable failure behavior, and an extension mechanism for application-specific types.

It should also distinguish between representations that are syntactically valid JSON and representations that carry the intended meaning for a particular application.

For example, the string "100" is valid JSON, but that does not tell us whether the application intended a string identifier or an integer. Likewise, a date string can be valid JSON without necessarily matching the representation expected by a database.

These decisions belong to the architecture, not just to the encoder.

In Capoerus, convert_json is one small component of a broader technology ecosystem. Its value comes from being focused, reusable, and adaptable to the requirements of the systems that depend on it.

Final thoughts

Building reliable software is not always about adopting a large framework or adding another dependency. Sometimes it is about identifying a recurring architectural concern and implementing a focused solution that can be maintained alongside the application.

convert_json is my approach to that problem in Dart: a pure-Dart package, available through GitHub, designed for controlled JSON encoding and decoding across the Capoerus ecosystem.

It is not a universal answer to serialization, and it does not remove the need for validation or error handling. Instead, it provides a place to centralize conversion rules, support custom object transformations, and adapt data to the formats required by the application.

For me, that is the main architectural benefit: having control over how data moves between Dart objects, JSON representations, and the systems that consume them.

Repository: https://github.com/Suebersson/convert_json

How do you handle custom types and database-specific serialization in your Dart applications? Do you prefer a general-purpose serialization framework, native JSON with custom adapters, or an internal conversion layer?

Contato • Website • Links • Play Store

Dart on Linux + Precompiled C++: Building a Native MongoDB Driver

Capoerus — Sun, 11 Oct 2026 17:07:13 +0000

Creating an API in Dart is relatively easy. The challenge begins when the API needs to run reliably in production and depends on secure, well-maintained components for database access, file management, request processing, and cross-platform data handling.

While developing Capoerus, I found that ready-made components did not always meet the requirements of my architecture. In some cases, I decided to build my own packages and technologies.

One of the most interesting engineering decisions was combining Dart compiled for Linux with a precompiled C++ MongoDB access driver.

This approach provides greater control over implementation, shared data representations, and reduced dependence on third-party packages. However, it also introduces challenges involving native memory management, error handling, and communication between programming languages.

This article explores how this combination works, why I chose it, and what I learned from the trade-offs.

1. The Challenge Goes Beyond Creating an API

Dart provides a productive environment for building APIs. However, a production system requires more than routing, request handlers, and asynchronous functions.

During the development of Capoerus, I needed several components:

A universal JSON encoding and decoding package shared by the frontend, backend, and native database driver.
A MongoDB access driver integrated with Dart.
Cloud file management for Oracle Cloud Infrastructure Object Storage.
A lightweight local database that stores data in JSON format on mobile and desktop devices, without requiring code generation.
A multipart request handler shared between the application and the API.

These components support an architecture in which mobile applications, web applications, and server-side code share a significant portion of their implementation.

Developing them independently required considerable effort. However, it also allowed me to establish consistent interfaces and behaviors across the entire ecosystem.

The MongoDB driver is a particularly interesting example because it crosses the boundary between Dart-managed code and native C++ execution.

2. Why Use C++ for the MongoDB Driver?

The API runs on Linux, compiled from Dart, while the MongoDB driver is implemented in C++ and compiled into a native library before deployment.

Dart communicates with native functions through FFI (Foreign Function Interface).

Instead of implementing every database operation entirely in Dart, the driver exposes native functions that can be called through their symbols.

For example, the Dart side declares an operation like this:

const String findOneSymbol = 'findOne';

@Native<Method>(
  assetId: assetId,
  symbol: findOneSymbol,
  isLeaf: isLeaf,
)
external Pointer<Utf8> findOne(Pointer<Utf8> request);

The findOne function represents a native entry point. Dart passes a pointer to the request, and the native function returns a pointer containing the response.

Each database operation has its own symbol, allowing operations to be exposed independently.

This gives the Dart layer a relatively small interface to work with while the native library handles the database-specific implementation.

It also means that the native library must respect a strict contract regarding memory, data representation, and return values.

That contract is where the most important engineering decisions begin.

3. A Bidirectional Buffer Shared by Dart and C++

The driver uses a buffer allocated on the Dart side for both the request and the response.

The process works as follows:

Dart serializes the request into JSON.
Dart encodes the JSON string into UTF-8 bytes.
Dart allocates a native memory buffer large enough for the request and the expected response.
The request bytes are copied into that buffer, followed by a null terminator.
Dart calls the native C++ function, passing the buffer pointer.
C++ processes the request and writes the response into the same buffer.
The native function returns the pointer to that buffer.
Dart reads the response, decodes the JSON, and releases the allocated memory.

Conceptually, the data flow looks like this:

Dart API
   |
   | Serialize request to JSON
   | Encode as UTF-8
   | Allocate response-capable buffer
   v
+------------------------------+
| Dart-allocated native buffer |
|                              |
| JSON request                 |
+------------------------------+
   |
   | FFI call
   v
+------------------------------+
| Precompiled C++ driver       |
|                              |
| Process request              |
| Execute MongoDB operation    |
| Write response into buffer   |
+------------------------------+
   |
   | Return the same pointer
   v
Dart API
   |
   | Read UTF-8 response
   | Decode JSON
   | Release allocation
   v
Application response

The key idea is that the native function does not need to allocate a separate response buffer and transfer ownership of that allocation to Dart.

Instead, Dart owns the allocation, and C++ writes the response into the memory provided by Dart.

This design reduces the complexity of memory ownership between the two layers. However, it does not automatically provide memory safety. The native implementation must respect the buffer's capacity and the agreed pointer contract.

4. Allocating Enough Memory Is the Difficult Part

The buffer must be large enough to contain the response, not merely the original request.

A small MongoDB query can return a large document. A query that returns multiple documents can produce a response considerably larger than its input.

If C++ writes beyond the allocated capacity, it can corrupt memory and crash the process.

For a server-side API, this is especially important because a native crash can terminate the entire process rather than just fail a single request.

The Dart implementation therefore accepts a response size limit and checks it against the encoded request size before allocating memory.

A simplified version of the validation is:

final Uint8List requestBytes = utf8.encode(request.toJson);

final int requestBytesLength = requestBytes.length;
final int responseSizeLimit = request.responseSizeLimit;

if (responseSizeLimit < requestBytesLength) {
  throw const MongodbException(
    'The response size limit cannot be smaller '
    'than the request size.',
  );
}

The actual implementation also reserves one additional byte for the null terminator.

This initial validation prevents an obviously undersized buffer from being passed to C++. However, it does not guarantee that the response will fit.

The native side must enforce the capacity before every write, and the driver must define what happens when a response exceeds the configured limit.

A robust implementation should reject oversized responses or return a controlled error rather than attempting to write beyond the buffer.

Why the Null Terminator Matters

The native function receives a pointer to UTF-8 data represented as a null-terminated string.

The allocation therefore includes an additional byte:

final Pointer<Uint8> allocatedPointer =
    malloc<Uint8>(responseSizeLimit + 1);

The request is then copied into the allocated memory:

final Uint8List nativeBytes =
    allocatedPointer.asTypedList(requestBytesLength + 1);

nativeBytes.setAll(0, requestBytes);
nativeBytes[requestBytesLength] = 0;

The zero byte marks the end of the C-style string.

When C++ writes the response, it must preserve that convention and ensure that the response and its terminator fit within the available memory.

The response must also be valid UTF-8 JSON before Dart attempts to decode it.

5. Keeping the Pointer Contract Explicit

Another important check verifies that the native function returns the same pointer that Dart originally allocated.

final int allocatedPointerAddress =
    allocatedPointer.address;

final Pointer<Utf8> requestPointer =
    allocatedPointer.cast<Utf8>();

final Pointer<Utf8> responsePointer =
    request.method(requestPointer);

if (allocatedPointerAddress != responsePointer.address) {
  throw const MongodbException(
    'The native function returned an unexpected pointer.',
  );
}

This is a simplified illustration of the pointer validation used by the driver.

The native functions are expected to write the response into the original allocation and return that same address.

This makes the ownership contract explicit: the native function must not return an independently allocated response buffer under the same interface.

One limitation is worth noting: checking the address after the native function returns cannot prevent an invalid write that has already occurred. Pointer validation is a contract check, not a substitute for bounds checking inside C++.

The native implementation must enforce the buffer capacity before writing any response bytes.

6. Dart Manages the Allocation, but the Trade-Off Remains

One benefit of this design is that Dart controls the buffer's allocation and release.

C++ does not need to transfer ownership of a separately allocated response buffer to the Dart layer. This avoids one class of cross-language ownership problems.

The Dart implementation can read the response and then release the allocation:

final String content = responsePointer.toDartString();

final Json json = Json.treaty(content);

malloc.free(requestPointer);

return json;

The example illustrates the intended lifecycle, but production code must handle cleanup on every execution path.

For example, if decoding throws an exception before malloc.free executes, the allocation could leak. A safer implementation places the native allocation in a try/finally lifecycle so that the buffer is released even when an operation fails.

The central trade-off remains:

Dart controls allocation and release.
C++ must respect the memory boundaries established by Dart.
A native buffer overflow can still crash the API.
Incorrect pointer handling can still cause undefined behavior.

This is one of the areas where native integration requires more care than an ordinary Dart function call.

7. Exceptions and Controlled Failures

A database driver should not assume that every operation succeeds.

MongoDB operations can fail, JSON responses can be invalid, and unexpected conditions can occur at the native boundary.

The driver therefore catches its own database-related exceptions and unexpected Dart-side exceptions, records diagnostic information, and can return an alternative JSON response.

The public interface includes an optional ifFail callback:

Future<Json> request(
  final Request request, {
  Json Function()? ifFail,
}) async {
  // Request processing and native invocation.
}

The callback allows the caller to supply alternative data when a request fails.

The general fallback behavior is:

return json ?? ifFail?.call() ?? Json.emptyMap();

This gives the calling code a way to handle failures without necessarily propagating every exception through the entire request-handling stack.

However, exception handling has an important boundary.

Catching Dart exceptions does not reliably recover from arbitrary native crashes, segmentation faults, or memory corruption. Those failures may terminate the process before Dart can execute its catch block.

For this reason, exception handling must complement, rather than replace, native validation and memory safety.

In addition, a fallback value should not make a failed database operation indistinguishable from a successful one. The application must preserve enough information to determine whether the requested operation actually succeeded.

8. Why Precompiled Native Code Requires a Security Strategy

Using a native library also changes the security considerations.

A precompiled library does not expose its implementation as readable source code in the deployed artifact. That can make its behavior harder to inspect during routine debugging, especially when debugging symbols and build artifacts are unavailable.

But compiled code is not inherently trustworthy, nor is it impossible to analyze.

A native library can contain vulnerabilities or perform unintended operations regardless of whether its source code is visible.

For a component that has access to a database and runs inside an API process, I consider control over the implementation an important advantage.

Developing the driver internally gives me control over its source code, its build process, its exposed functions, and the changes introduced between versions.

It also allows the interface between Dart and C++ to remain narrow and explicit.

Still, these benefits should not be confused with an automatic security guarantee.

A custom driver needs code review, dependency management, controlled builds, tests, and careful validation of native inputs. The same applies to permissions and access credentials: the native library should only receive the capabilities it actually needs.

Owning the implementation improves control; security still depends on how that implementation is built, reviewed, and operated.

9. One JSON Language Across the Ecosystem

The native MongoDB driver is only one part of the architecture.

Another important component is the JSON encoding and decoding package developed for Capoerus.

The same representation is used across the mobile application, backend, and native driver.

This reduces the number of translation layers required between components.

Instead of maintaining different data representations for each platform, the system uses a shared JSON contract.

The result is a more consistent flow of data:

Mobile application
       |
       | JSON
       v
Dart application and API
       |
       | JSON encoded as UTF-8
       v
Native C++ MongoDB driver
       |
       | JSON response
       v
Dart API and application

JSON does not eliminate the need for validation or versioning. A shared format still requires consistent handling of missing fields, data types, invalid responses, and schema changes.

Its value is that the components share a common representation and can evolve around the same conventions.

10. The Benefits Extend Beyond MongoDB

Developing the native driver makes more sense when considered alongside the other components created for the ecosystem.

Capoerus also uses its own solutions for local JSON-based storage, cloud file management with Oracle Cloud Infrastructure Object Storage, JSON serialization, and multipart request handling.

These components address different problems, but they follow a common architectural principle: establish interfaces that work consistently across the applications and services that need them.

This approach has practical advantages:

Consistency: mobile, web, and server components share common conventions.
Autonomy: implementation decisions are not entirely dependent on external package maintainers.
Adaptability: changes can be coordinated across the ecosystem.
Reduced dependency surface: fewer third-party components are required for the functionality implemented internally.
Control over updates: internal components can evolve according to the project's needs.

None of these advantages means that building everything in-house is automatically better.

Maintaining custom infrastructure creates responsibilities that would otherwise belong to package maintainers. Security updates, compatibility, testing, documentation, and debugging become part of the project's own workload.

The benefits must justify that ongoing cost.

11. The Cost of Building Your Own Technology

There is a downside to this approach that is easy to underestimate.

Creating a package is only the beginning.

It must be tested, documented, maintained, and adapted as the application evolves. Native code adds another layer of complexity because failures can occur outside Dart's managed execution environment.

A third-party package with a mature implementation may be a better choice for many projects.

For Capoerus, however, developing these components has provided a high degree of autonomy and a consistent technical foundation across the ecosystem.

The decision was not simply to avoid dependencies. It was to build components whose behavior and interfaces could be coordinated with the rest of the architecture.

That distinction matters.

Reducing dependencies is useful only when the cost of owning the replacement remains manageable.

Conclusion

Combining Dart compiled for Linux with a precompiled C++ MongoDB driver has allowed Capoerus to establish a direct interface between its API and native database operations.

The design uses a Dart-allocated buffer for both request and response data, making memory ownership easier to define. It also creates strict requirements for buffer capacity, pointer identity, null termination, exception handling, and cleanup.

The larger benefit comes from how this component fits into the rest of the system.

A shared JSON representation, custom local storage, cloud file management, and reusable request-processing components help keep mobile applications, web applications, and server-side code aligned.

The price is substantial engineering and maintenance work. The reward is greater control over implementation, fewer unnecessary translation layers, and the freedom to adapt components to the needs of the project.

For me, the most important lesson is not that native C++ is always the right choice for a Dart backend.

It is that the boundary between two languages can become a useful architectural tool when its ownership rules, data contract, and failure modes are designed explicitly.

That boundary is also where the most careful engineering is required.