Contributing

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

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.