Matrix Directory

A community directory for bots, frameworks, SDKs, and tools in the Matrix ecosystem.

Matrix Directory is a community-driven web application for discovering projects in the Matrix ecosystem, including bots, frameworks, SDKs, and other tools.

It provides a Vue frontend for discovering and managing projects and a FastAPI backend for authentication, profiles, project ownership, and directory data.

Tech stack

• Frontend: Vue 3, TypeScript, Tailwind CSS
• Backend: FastAPI, SQLModel
• Database: PostgreSQL
• Migrations: Pelican
• Authentication: Matrix Authentication Service / OpenID Connect
• Development: Docker Compose

Development

Requirements

• Docker with Docker Compose
• cloudflared only when testing Matrix login locally

Start the application with Docker Compose:

docker compose up --build

The services will be available at:

• Frontend
• Swagger UI

The backend automatically applies database migrations on startup.

Stop the services:

docker compose down

Reset the local database:

docker compose down -v

Authentication

Matrix Directory authenticates users through the Matrix Authentication Service (MAS) using OpenID Connect.

Application accounts are identified by the OIDC (issuer, subject) pair. During login, the backend resolves the authoritative Matrix ID by calling the homeserver /_matrix/client/v3/account/whoami endpoint with the MAS access token.

Matrix avatars use an authenticated backend thumbnail proxy. Set a stable MATRIX_TOKEN_ENCRYPTION_KEY (a Fernet key) before enabling Matrix login:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

The backend encrypts the OAuth refresh token, then uses it only to stream the Matrix v1 thumbnail endpoint. Neither Matrix OAuth token is exposed to the browser.

For local development with a real Matrix account, use the helper script to register an OAuth client and start an HTTPS tunnel:

python scripts/dev_matrix_tunnel.py

See Authentication Architecture for details about identity, sessions, and authorization.

API

Interactive API documentation is available at:

• Swagger UI

Core endpoints include:

GET  /api/health
GET  /api/projects/
GET  /api/projects/mine/
GET  /api/projects/{project_id}
POST /api/projects/
PATCH /api/projects/{project_id}
DELETE /api/projects/{project_id}

GET  /api/project-types/
GET  /api/labels/

GET  /api/auth/matrix/login
GET  /api/auth/matrix/callback
GET  /api/auth/me
POST /api/auth/logout

Project IDs are UUIDs.

Project creation, updates, and deletion require an authenticated session. Ownership is derived from that session; callers cannot choose a project user_id.

Migrations

Migrations are in backend/db/migrations and use Pelican.

cd backend
export DATABASE_URL='postgresql+psycopg://matrix:matrix@localhost:5432/matrix_directory'
pelican status
pelican up
pelican down

Contributing

We welcome everyone to contribute! Whether it's fixing bugs, suggesting features, or improving the docs. Every bit helps.

• Submit an issue
• Open a pull request
• Hop into our Matrix or Discord and say hi!

Please read the CONTRIBUTING.md and follow the code of conduct.

License

Released under the MIT License.