Firmiana
  • English

      • Introduction

      Firmiana is a lightweight, self-contained Matrix protocol homeserver implementation. It provides a local single-server Client-Server homeserver suitable for development, testing, and small-scale deployments.

      What is Matrix?

      Matrix is an open standard for decentralised, persistent communication. It defines APIs for:

      • Client-Server API — How clients (Element, Cinny, Element X) talk to a homeserver
      • Server-Server API — How homeservers federate with each other
      • Application Service API — How external services integrate with a homeserver

      Firmiana currently implements the full Client-Server API and a substantial subset of the Server-Server (federation) API.

      Why Firmiana?

      ProblemFirmiana's Solution
      Synapse requires PostgreSQL and complex setupEmbedded H2 database, zero external dependencies
      Dendrite is written in Go (different ecosystem)GraalVM JDK 21, Micronaut framework
      Testing Matrix clients needs a running serverFast startup, in-memory mode available
      Federation is hard to test locallyFull federation stack with local signing

      Architecture at a Glance

      Client (Element/Cinny/Element X)
        │
        ▼
┌─────────────────────────────┐
│   Micronaut HTTP Server     │
│   (Netty, port 8899)        │
├─────────────────────────────┤
│   Controllers (43+)         │  ← Matrix Client-Server API routes
├─────────────────────────────┤
│   Services                  │  ← Business logic
├─────────────────────────────┤
│   Repositories              │  ← Micronaut Data JDBC
├─────────────────────────────┤
│   H2 Database               │  ← Embedded, file-based
│   Flyway Migrations (V1-V23)│
└─────────────────────────────┘

      Key Capabilities

      • Authentication: Bearer token auth, UIAA registration flows, device management
      • Rooms & Events: Full event DAG, state resolution, membership, redaction
      • Sync: Long-polling /sync, stream tokens, ephemeral events
      • E2EE: Key upload/query/claim, cross-signing, device keys, to-device messages
      • Media: Upload, download, thumbnails, URL preview with SSRF protection
      • Federation: Request signing, key caching, transaction processing, inter-server join/invite/leave
      • Push: Push rules, pushers, notifications
      • Admin: User/room management, health checks, rate limiting

      Current Status

      All phases P0–P5 are complete with 244 tests passing. See Roadmap for detailed status.