Psyche

A high-performance, high-security, local-first media server written in Rust.

Your data. Your machine. Your rules.

---

What Is Psyche?

Psyche is a self-hosted media server for people who care about their data. It indexes, streams, and organises your local media library — anime, manga, TV shows, books, and music — with a focus on security, speed, and audibility.

No cloud required. No telemetry. No subscriptions.

Every remote feature is opt-in. Every opt-in feature has a local alternative. A user who never connects Psyche to the internet still gets a complete, fully-featured experience.

---

Core Principles

• Local-first. Your media never leaves your machine unless you say so.
• Security by default. Sensitive metadata is encrypted at rest. An attacker with filesystem access gets ciphertext, not your watch history.
• Speed without compromise. Rust all the way down. No garbage collector, no Python glue, no memory leaks.
• Auditable. Plain SQL migrations. Typed errors. No magic. No ORMs hiding queries from you. Every architectural decision is documented in docs/.
• Paranoid-user path. Remote integrations (AniList, TMDB, LLM providers) all have offline alternatives — including a local Kitsu database dump for anime metadata with zero outbound connections.

---

Features

Current (Phase 0 — foundation complete)

• Cargo workspace with psyche-api and psyche-core
• Minimal Axum API server with GET /health returning {"status":"ok"}
• React 19 + Vite 8 + Tailwind 4 frontend in psyche-site/ with mock data only

Planned

Feature	Status
Manga reader + OCR translation	Planned
TV show library	Planned
Music streaming + lyrics	Planned
Books (EPUB/PDF) + translation	Planned
Metadata encryption at rest	Planned
fill-metadata ML pipeline	Planned
psyche-translate crate	Planned
Sonarr / Radarr / arr stack	Planned
Discord rich presence + bot	Planned
Torrent streaming	Planned
Plugin system	Planned
Community P2P layer (opt-in)	Planned
Android + Desktop (Tauri) apps	Planned

The full vision is in docs/VISION.md.

---

Tech Stack

Concern	Choice
Language	Rust 2024 edition
HTTP	Axum 0.8
Async runtime	Tokio
Database	SQLite via sqlx 0.8 (async, compile-time SQL)
Auth	JWT (HS256) + Argon2id
Filename parse	zantetsu-core 0.1
Frontend	React 19 + Vite 8 + Tailwind 4

---

Project Structure

psyche/
├── AGENTS.md           ← AI pair programming rules and living spec
├── CONTRIBUTING.md     ← How to contribute
├── LICENSE             ← GNU GPL v3
├── docs/
│   ├── VISION.md       ← Full product vision
│   ├── ARCHITECTURE.md ← Current system architecture
│   └── SECURITY.md     ← Threat model and encryption decisions
├── psyche-api/        ← Binary crate: HTTP server, routes, middleware
├── psyche-core/       ← Library crate: domain logic, DB, scanner
└── psyche-site/       ← React frontend (Vite + Tailwind)

---

Getting Started

Prerequisites

• Rust (latest stable) — rustup.rs
• Bun — bun.sh (for the frontend)
• SQLite (usually pre-installed on Linux/macOS)

Build and run

# Clone the repository
git clone https://github.com/yourusername/psyche.git
cd psyche

# Run the API server
cargo run -p psyche-api

The server starts on http://localhost:3000 by default.

Configuration

Current Phase 0 runtime configuration is intentionally minimal:

• The API listens on 0.0.0.0:3000
• No environment variables are required yet
• Database and authentication configuration begin in a later slice

---

Branches

Branch	Purpose
main	Stable releases. Always builds. Always tested.
dev	Beta. Next features land here before promotion.

Download the latest stable release from the Releases page, or pull main and build from source.

---

Security

The security model is documented in full in docs/SECURITY.md.

To report a vulnerability, do not open a public issue. Send a private report via GitHub's Security Advisory feature or email the maintainer directly. Include a description of the issue, reproduction steps, and potential impact.

---

Contributing

Read CONTRIBUTING.md before opening an issue or pull request.

The short version:

• Issues must include a screenshot or log. Vague reports are closed.
• All code contributions require tests that pass on the project's test suite.
• AI-generated code is permitted only if the contributor has read, understood, tested, and takes full responsibility for every line. Unreviewed AI slop is rejected immediately.
• All PRs target the dev branch, not main.

---

License

Psyche is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

See LICENSE for the full text.

This license was chosen deliberately. It requires that any derivative work — including forks used commercially — must remain open source under the same terms. You cannot take Psyche, close the source, and sell it.