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 listings 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
• API documentation

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 rather than by a Matrix ID.

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/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.