# 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:

- Expose a stable HTTP API as the primary interface for all clients.
- Host and render DIY project content through a bundled web UI that consumes the public API.
- 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.

## Client and Front-End Strategy

The server exposes a stable, documented HTTP API as its primary interface. The bundled web UI is a first-party client of that same API — it receives no privileged server-side access that a third-party client could not also use.

Principles:

- **API-first**: every user-facing capability is reachable through the public API before the bundled UI uses it.
- **No server-side rendering shortcuts**: the bundled UI must not depend on server-internal state or bypass the API layer.
- **Third-party clients are first-class**: authentication, content negotiation, and capability negotiation must work the same way for any client origin.
- **Content negotiation**: the server responds to `Accept: application/activity+json` (or `application/ld+json`) for federation endpoints, and `Accept: application/json` for the API, allowing a single URL namespace to serve both.
- **CORS**: cross-origin API access is supported for read-only public resources, with authenticated endpoints requiring explicit opt-in by the instance operator.
- **Bundled UI is optional at deploy time**: an instance operator should be able to run the backend and serve their own front-end without modifying server code.

API surface areas:

- Public read API: browse projects, actors, and search without authentication.
- Authenticated user API: authoring, account management, preferences.
- Moderation API: moderation actions and audit review, scoped by role.
- Federation endpoints: ActivityPub inbox/outbox per the ActivityPub specification.
- Well-known endpoints: WebFinger, NodeInfo, and instance metadata.

Bundled web UI:

- Delivered as static assets served from the same origin.
- Communicates only through the public API.
- Treated as the reference client for API usability validation.
- Should degrade gracefully where JavaScript is unavailable where practical.

## Logical Components

- Public HTTP API layer (routing, auth middleware, content negotiation, CORS).
- 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.
- Bundled web UI (static asset delivery).
- 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, and safe CORS policy.
- Performance: predictable latency for local reads and bounded queues for remote events.
- Operability: metrics, logs, and runbooks for incident response.
- API stability: public API changes follow a deprecation policy; breaking changes require a version increment.

## Architecture Decision Practice

- Decisions are captured as ADRs in [docs/adrs/](adrs/).
- Each ADR includes: context, options considered, decision, and consequences.
- See [ADR 0001: API-First with Bundled Web UI](adrs/0001-api-first-bundled-ui.md).