EN Architecture

Architecture and request lifecycle

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Forge has two management levels. The application API handles end-user and service traffic; the Editor control plane manages source documents, team members and the workspace. They use separate credentials and network policies.

flowchart TD
  A["Application client"] --> B["ASGI and protection"]
  B --> C["Project selection and authorization"]
  C --> D["CRUD, RPC or hook"]
  D --> E["Project SQL, MongoDB and cache"]
  F["Desktop Editor"] --> G["Management identity and scopes"]
  G --> H["Document validation and atomic save"]
  H --> I["JSON reload"]
  I --> C

Loading

From configuration to a running service

1. Discover explicit project roots under app/.
2. Merge the manifest and numbered JSON fragments; resolve $env: references.
3. Run strict Pydantic and semantic validation. Unknown fields are errors.
4. Expand enabled feature packs into ordinary resource definitions.
5. Create each project's SQL, MongoDB, cache, rate-limit, event and media services through ProjectRuntime.
6. Register the configured HTTP surfaces and generate OpenAPI.
7. Manage connections and resources through lifespan startup/shutdown.

Source map

Area	Main files	Responsibility
Models and loading	framework/config.py, schema.py	Types, merge, environment resolution, discovery
Application	factory.py, runtime.py, reload.py	ASGI, lifecycle and reload
Project API	routers/project.py	CRUD/RPC/data/custom routes
Data	db.py, crud.py, operations.py, mongo.py	Access and transaction rules
Identity	security.py, protection.py	Principals, permissions and request protection
Management	editor_api.py, editor_identity.py, editor_database.py	Team and document operations
CLI	cli.py, doctor.py	Creation, inspection and migration

Isolation boundaries

Projects have separate slugs, API prefixes, roles and service configuration. They can still share a Python process, CPU/memory, global settings and the internal identity database. An invalid JSON update can be rejected without stopping unrelated applications, but this is not an operating-system sandbox. Untrusted hooks, native crashes and resource exhaustion require separate processes or containers.

framework.factory.create_app() creates a configuration snapshot. Normal development and source entry points use framework.reload:create_live_app to watch JSON changes. See hot reload.

Checks on an HTTP request

Host/IP/HTTPS and size policies, pre-auth limits, authentication, permissions, tenant/ownership rules, input schemas, database work and response bounds work together. CORS, an obscure URL or a disabled Editor button does not provide authorization. Cached data must retain the server-established caller context.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/factory.py
• main/framework/runtime.py
• main/framework/reload.py
• main/docs/01-Architecture.md

---

English home · All English pages · Version maintenance