Modular Architecture Patterns for JSON Formatting Tools

Building robust and maintainable software requires careful consideration of its architecture. For JSON formatting tools, which often need to handle diverse inputs, various formatting styles, and potential validation steps, a modular architecture is particularly beneficial. Modularity breaks down a system into smaller, independent, and interchangeable parts, making development easier, updates smoother, and extension simpler.

Why Modularity for JSON Tools?

JSON formatters and validators are not monolithic tools. They typically involve several distinct processes:

• Parsing the input JSON string.
• Validating its syntax and potentially its structure/schema.
• Representing the JSON data in memory (e.g., as an Abstract Syntax Tree or object).
• Applying formatting rules (indentation, spacing, sorting keys).
• Serializing the formatted data back into a string.
• Handling errors.

Each of these steps can be treated as a module. By designing the tool with clear boundaries between these modules, you gain significant advantages:

Common Modular Patterns

1. Layered Architecture

This pattern organizes the codebase into horizontal layers, each with a specific responsibility. Layers typically only interact with the layers directly above or below them.

In this model, the Presentation Layer talks to the Application Layer, which uses components from the Domain Layer to perform the actual JSON processing.

2. Plugin or Extension Architecture

This pattern is excellent for tools that need to support various, potentially user-provided, functionality, such as different formatting styles, sorting options, or validation rules (like JSON Schema). A core system defines interfaces or abstract classes, and plugins provide concrete implementations.

interface JsonFormatterPlugin {
  name: string; // e.g., "standard-indent-4", "compact", "sorted-keys"
  description: string;
  format(jsonString: string, options?: any): string;
}

// Example Implementation for Standard Indentation
class StandardIndentFormatter implements JsonFormatterPlugin {
  name = "standard-indent-4";
  description = "Formats JSON with 4-space indentation.";

  format(jsonString: string): string {
    try {
      const obj = JSON.parse(jsonString);
      return JSON.stringify(obj, null, 4);
    } catch (error: any) {
      throw new Error(`Formatting failed: ${error.message}`);
    }
  }
}

// Core application logic
class JsonToolCore {
  private formatters: Map<string, JsonFormatterPlugin> = new Map();

  registerFormatter(plugin: JsonFormatterPlugin): void {
    this.formatters.set(plugin.name, plugin);
  }

  getFormatter(name: string): JsonFormatterPlugin | undefined {
    return this.formatters.get(name);
  }

  // Method to format using a specific plugin
  format(jsonString: string, formatterName: string, options?: any): string {
    const formatter = this.getFormatter(formatterName);
    if (!formatter) {
      throw new Error(`Formatter "${formatterName}" not found.`);
    }
    return formatter.format(jsonString, options);
  }
}

// Usage:
const tool = new JsonToolCore();
tool.registerFormatter(new StandardIndentFormatter());

try {
  const unformatted = '{"name":"Test","value":123}';
  const formatted = tool.format(unformatted, "standard-indent-4");
  console.log(formatted);
} catch (error: any) {
  console.error(error.message);
}

3. Pipeline Architecture

A pipeline architecture treats the data processing as a sequence of stages, where the output of one stage becomes the input of the next. This is highly suitable for JSON processing, which naturally flows from parsing to validation to formatting to serialization.

Each stage can be implemented as a separate module. This makes it easy to insert new stages (like schema validation) or replace existing ones (like using a different JSON parser) without affecting the overall structure.

function processJson(jsonString, config) {
  let data = jsonString;

  // Stage 1: Parsing
  const parsedData = parseJson(data); // Uses a Parser module

  // Stage 2: Validation (Optional)
  if (config.validate) {
    validateJson(parsedData, config.schema); // Uses a Validator module
  }

  // Stage 3: Transformation/Formatting
  const formattedData = applyFormatting(parsedData, config.formatRules); // Uses Formatter modules

  // Stage 4: Serialization
  const outputString = serializeJson(formattedData); // Uses a Serializer module

  return outputString;
}

// Each function (parseJson, validateJson, etc.) would be a call to a separate module
// applying specific logic.

Choosing the Right Pattern

The best pattern depends on the complexity and requirements of your tool:

• Layered: Good for separating core logic from UI/infrastructure concerns.
• Plugin/Extension: Ideal when you anticipate adding many different variations of a specific function (like formatters or validators) without changing the core logic.
• Pipeline: Natural fit for processing data through a sequence of operations. Can often be combined with Plugin architecture (e.g., a "Formatting" stage in the pipeline could use the Plugin pattern to select different formatters).

Often, a combination of patterns is the most effective approach. For example, you might use a Layered architecture overall, but within the 'Domain' layer, implement a Pipeline for the core processing flow, and use a Plugin pattern for the specific formatting or validation steps within that pipeline.

Implementation Considerations

• Clear Interfaces: Define how modules interact using well-defined interfaces or API contracts.
• Dependency Injection: Use techniques like dependency injection to manage how modules receive the resources they need, reducing tight coupling.
• Error Handling: Design a consistent way for modules to report errors back up the chain or layers.
• Configuration: Provide a flexible way to configure different modules and their behavior.

Conclusion

Adopting a modular architecture is a strategic choice that pays off as a JSON formatting tool evolves. It transforms a potentially tangled codebase into an organized, adaptable system. By identifying the distinct concerns (parsing, formatting, validating, etc.) and encapsulating them into modules, you create a tool that is easier to build, test, maintain, and extend. Whether you choose a Layered, Plugin, or Pipeline pattern, or a combination, the principles of high cohesion and low coupling will guide you towards a robust and future-proof design.