Contributing

How to contribute to Phiacta — setting up a development environment, submitting code, and reporting issues.

Have an idea? We'd love your help.

Phiacta is built on a plugin architecture, which means adding new features is genuinely straightforward — the same framework that powers search, tags, and LaTeX compilation is available to everyone. If there's something you want to see on the platform, you're totally free to build it. Open an issue to discuss your idea, or jump straight into a pull request. I'm happy to help you get oriented in the codebase and answer questions along the way — reach out at [email protected].

Feature ideas

Here are some features we've been thinking about but haven't built yet. Any of these would make a great contribution — or bring your own idea.

Automated review papers

Agents that read related entries and synthesize them into survey or review papers — using the reference graph and semantic search to find connections.

Podcast generation

Turn entries into audio — AI-generated podcast episodes that explain and discuss the content, tailored to different audiences.

User expertise profiles

Build a private knowledge profile from a user’s publications, comments, and edits. Only visible to the user — agents can use it to generate better explanations tailored to the reader’s background.

Personalized reading feeds

Surface relevant entries based on what you’ve published, read, and cited. Built on expertise profiles and the reference graph.

Community reviews

Open, transparent quality signals. Anyone can leave a structured review with ratings on dimensions like clarity, rigor, and reproducibility. No gatekeeping — just public signal that helps readers evaluate entries.

Verification (coming soon)

Sandboxed execution of code that users mark for verification — reproduce empirical results and generate cryptographically signed reports.

Semantic search

Use pgvector embeddings to find entries by meaning, not just keywords. Makes agent-driven discovery and contradiction detection much more powerful.

Citation export

Generate BibTeX, RIS, or other citation formats from entry metadata and references.

DOI integration

Register DOIs for entries or link to existing DOIs for cross-referencing with external literature.

Version comparison

Side-by-side diff between any two commits in an entry’s history.

Project structure

Phiacta is split across several repositories, each with a focused responsibility.

phiacta

Python/FastAPI backend. Contains the API, database models, plugin system, Forgejo integration, and all server-side logic.

Python 3.12, FastAPI, SQLAlchemy, PostgreSQL, Forgejo API

phiacta-web

Next.js website. The web UI for browsing, creating, and managing entries.

Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui

phiacta-mcp

Model Context Protocol server. Lets AI agents interact with Phiacta programmatically.

TypeScript, MCP SDK

phiacta-sdk-python

Python client library for the Phiacta API. Async-first with Pydantic models.

Python 3.11+, httpx, Pydantic

phiacta-deploy

Docker Compose stacks and deploy script. Clone this alongside the other repos to spin up a full dev environment.

Docker, Docker Compose

phiacta-verify

Verification integration. Being merged into the backend as a verification extension.

Python

Deprecated — will be folded into the backend repo as an extension plugin.

Local dev environment

The dev stack runs entirely in Docker. You need Docker and Docker Compose installed.

1

Clone the repos side by side

git clone https://github.com/Noah-Everett/phiacta.git
git clone https://github.com/Noah-Everett/phiacta-web.git
git clone https://github.com/Noah-Everett/phiacta-deploy.git
cd phiacta-deploy
2

Start the dev stack

./deploy.sh
3

Verify everything is running

# API:     http://localhost:8000/health
# Web:     http://localhost:3001
# Forgejo: http://localhost:3000

Stack: PostgreSQL 16 + Forgejo (git backend) + FastAPI (API) + Next.js (web). Ports: API on 8000, web on 3001, Forgejo on 3000, Postgres on 5433.

Contributing code

Pull requests

  • Fork the relevant repo and create a feature branch.
  • Keep PRs focused — one feature or fix per PR.
  • Write tests for new functionality. E2E tests are especially valued.
  • Run the existing test suite before submitting.

Code style

  • Backend: Ruff for linting and formatting. Type hints required. Follow existing patterns.
  • Frontend: ESLint + Prettier. TypeScript strict mode. shadcn/ui for components.
  • Mirror existing code — find the closest analogous implementation and match its structure.

Testing

  • Backend: pytest with async support. E2E tests hit a real database.
  • Frontend: Playwright for E2E, Vitest for unit tests.
  • Every new feature should have E2E tests that exercise the full path.

Reporting issues

Found a bug or have a feature request? Open an issue in the relevant repository.

API / backend bugsphiacta
Website bugsphiacta-web
MCP server bugsphiacta-mcp
SDK bugsphiacta-sdk-python

Include steps to reproduce, what you expected, and what actually happened. Screenshots or error messages are always helpful.