# Platform Repository Architecture Specification v1.0
## 1. Purpose
This document defines the architecture, structure, and governance model for the **Platform Repository System**, which supports:
- Centralized shared modules across multiple technologies
- Deterministic application generation
- Elimination of duplicate core modules (e.g., `/auth`, `/settings`)
- Cross-platform consistency (Rust, React, Kotlin, Swift)
- Production-grade build reproducibility
- Controlled extension via overlays
---
## 2. Design Principles
### 2.1 Single Source of Truth
All shared modules exist **only once**, in the upstream platform repository.
### 2.2 Composition Over Duplication
Applications are composed from upstream modules + local overlays.
No copying or forking of shared modules.
### 2.3 Deterministic Builds
Every build must be reproducible and traceable.
### 2.4 Explicit Versioning
All modules and builds are version-pinned via manifests and lockfiles.
### 2.5 Controlled Extensibility
Customization is allowed only through defined extension points.
### 2.6 Production-First Design
The system is designed for production environments, not ad hoc development.
---
## 3. Repository Model
The system uses a **two-repository architecture**:
### 3.1 Upstream Repository
**Name:** `platform-upstream`
Purpose:
- Houses all shared modules
- Defines manifests and compatibility rules
- Provides generators and validation tooling
### 3.2 Application Repositories
**Pattern:** `app-<name>`
Purpose:
- Define application configuration
- Contain overlays and deployment logic
- Consume upstream modules
---
## 4. Upstream Repository Structure
```text
platform-upstream/
├── docs/
├── schemas/
├── manifests/
├── shared/
│ ├── rust/
│ ├── web/
│ ├── kotlin/
│ └── swift/
├── generators/
├── scripts/
├── examples/
└── .github/
Documentation for:
JSON/YAML schemas for validation:
schemas/
├── app-config.schema.json
├── module-manifest.schema.json
└── compatibility.schema.json
Defines all modules, stacks, and compatibility rules.
manifests/
├── modules/
├── stacks/
└── compatibility/
Each shared module has a manifest describing:
Defines preset configurations:
Defines:
Contains all canonical modules.
shared/rust/crates/
├── core/
├── auth/
├── profile/
├── settings/
├── rbac/
└── ...
shared/web/packages/
├── core-ui/
├── auth-ui/
├── settings-ui/
└── ...
shared/kotlin/modules/
├── core/
├── auth/
├── settings/
└── ...
shared/swift/modules/
├── CoreKit/
├── AuthKit/
└── ...
Contains project generation and build orchestration tools.
generators/
├── app-init/
├── manifest-resolver/
├── build-orchestrator/
└── validators/
Operational scripts:
scripts/
├── bootstrap/
├── verify/
├── release/
└── ci/
Reference applications demonstrating valid configurations.
app-myproduct/
├── app.yaml
├── docs/
├── overlays/
├── services/
├── generated/
├── scripts/
└── deploy/
Defines the application composition.
Example:
app_name: myproduct
stack: fullstack
platforms:
- rust
- web
- kotlin
modules:
- core
- auth
- profile
- settings
- blog
channels:
core: stable
auth: stable
blog: beta
version_policy:
lockfile: true
require_compatibility_check: true
Contains app-specific extensions.
overlays/
├── rust/
├── web/
├── kotlin/
└── swift/
Rules:
Generated service entry points.
services/
├── api/
├── web/
├── android/
└── ios/
Build artifacts and metadata:
generated/
├── manifests.lock
├── build-plan.json
└── compatibility-report.json
App-level operations:
scripts/
├── sync-upstream.sh
├── verify.sh
└── build.sh
Deployment configurations:
name: auth
version: 1.4.0
platforms:
rust:
package: auth
web:
package: "@platform/auth-ui"
depends_on:
- core
- rbac
extension_points:
- auth_provider
- login_flow
overlay_policy:
allow_route_extensions: true
allow_entity_override: false
The following module names are protected:
No application may redefine these.
app.yamlEvery build must record:
manifests.lock)Locks:
stablebetaexperimentalResponsible for:
Responsible for:
Must validate:
Planned enhancements:
This architecture ensures:
The system is designed to support long-term production use across multiple applications and teams without duplication or divergence.