Architecture Principles

This document explains the design philosophy driving ContentGrid’s architecture and the principles that guide technical decisions. Understanding these principles helps evaluate how the platform aligns with your requirements and technical values.

Foundational Principles

API-First

The application exposes a REST API as the only interaction point—for both end-users and external automations. There is no separate “admin API” or backend interface; everything flows through the same well-defined API.

The REST API uses the HAL response format. HAL’s hypermedia links allow referencing related endpoints and discovering capabilities dynamically. At the same time, the core data is available as plain JSON objects—developers who don’t need HAL’s hypermedia features can simply use the standard JSON payload.

For a single application with a known model, the API structure is regular and predictable. HAL becomes essential when building generic tools that need to work across multiple different models (e.g., different projects or organizations). These generic consumers use HAL to adapt automatically to any data model.

Model-First

The API is generated directly from your relational content model. Entities with attributes and relations map naturally to URLs you’d expect from a hand-crafted application. For example, an invoice entity generates /invoices and /invoices/{id} endpoints automatically.

The data APIs don’t expose model abstractions like “entity,” “attribute,” or “relation” in their payload structure. These concepts are internal implementation details. Your API consumers work with invoices, suppliers, and documents—domain concepts, not meta-model concepts.

For developers building generic integrations, a separate model API (/profile and /profile/{entity}) does expose the entity and attribute metadata. This information is static for a particular application version and enables automations to adapt to any model without hardcoded entity knowledge.

Small Core

The application core provides only essential ECM functionality that cannot be implemented externally. Everything else is pushed to external automations.

Why keep the core small?

  1. Scalability: Core functionality is critical for the functioning of ContentGrid. Keeping it small makes it easier to scale this part horizontally, making sure it can handle the requests with good response times.

  2. Reduced Security Surface: Fewer features in the core mean fewer places where permission checks can be misconfigured. A smaller codebase is easier to audit and secure.

  3. Easier Maintenance: A well-defined, focused core is easier to understand, test, and maintain. The dynamic nature of model-driven applications already introduces complexity—keeping the core small manages this complexity.

Extensibility

Extensions add capabilities beyond the core platform while remaining loosely coupled. They can be developed in-house, by customers, or by third parties.

Extensions are not implicitly trusted. Token-based authentication ensures users and extensions have appropriate access without exposing primary credentials. Extensions can act on behalf of users (delegated access) or under their own identity (system access). When extensions act on behalf of users, they receive at most the user’s privileges—never more.

This security model enables safe integration of third-party services while maintaining ContentGrid’s permission model. Extensions access data through the same REST API as any other client, ensuring consistent authorization enforcement.

Summary

ContentGrid’s architecture principles prioritize developer experience, operational flexibility, and data security. By keeping the core small and designing for extensibility, the platform enables rapid development while maintaining long-term maintainability.

The model-first, API-first approach generates intuitive, standards-compliant REST APIs from your domain model. The clear separation between core and automations provides flexibility without sacrificing integration quality.