FedDIY/docs/ARCHITECTURE.md

FeDIY Architecture (Planning Baseline)

This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature.

System Boundaries

Primary system responsibilities:

• Host and render DIY project content.
• Manage local accounts and authorization.
• Federate selected objects and activities using ActivityPub.
• Enforce local moderation policy for both local and remote content.

Out of scope for early phases:

• Rich social graph features beyond project-oriented interactions.
• Highly customized recommendation systems.

Core Domains

• Identity and actors.
• Project authoring and publishing.
• Federation transport and protocol translation.
• Moderation and trust policy.
• Search and discovery.

Logical Components

• API and web delivery layer.
• Domain service layer for project and account workflows.
• Federation layer (inbox/outbox, signing, verification, retries).
• Persistence layer for local and federated records.
• Moderation policy engine and audit log.
• Background workers for delivery, indexing, and maintenance tasks.

Data and Object Strategy

• Separate local canonical records from imported federated records.
• Preserve source metadata for remote content and actor provenance.
• Track object lifecycle states to support idempotent federation processing.

Federation Strategy

• Start with a narrow, explicit ActivityPub profile.
• Prefer strict validation and clear rejection reasons over permissive parsing.
• Use replay-safe request validation and deterministic retry behavior.
• Maintain an interop test matrix for protocol behaviors.

Moderation and Safety Strategy

• Local policy is authoritative for what is visible on this instance.
• Policy controls exist at three levels: object, actor, and instance.
• Moderation actions produce auditable events.
• Appeals and reversal policy should be documented before broad federation rollout.

Non-Functional Requirements

• Reliability: resilient delivery and retry strategy for federated traffic.
• Security: signature verification, key management, least-privilege defaults.
• Performance: predictable latency for local reads and bounded queues for remote events.
• Operability: metrics, logs, and runbooks for incident response.

Architecture Decision Practice

• Capture major decisions with lightweight ADRs in a future docs/adrs directory.
• Each ADR should include context, options considered, decision, and consequences.