Developer Guide
Build sources and hosts for Alethia
Developer Guide
Welcome to the Alethia developer documentation. This guide will help you understand the architecture and build your own sources.
Precaution
This app aim's to be "just another manga reader". While there is intention to maintain a degree of quality and accuracy both in the app itself and supporting documentation, there may be occasional inaccuracies or outdated information.
Code is as of current-state closed-source but I will personally guarantee open-sourcing once the code itself is documented sufficiently for public contribution.
Architecture Overview
Alethia uses a host-source architecture where content is fetched through intermediary deployable servers.
Key Concepts
| Term | Description |
|---|---|
| Host | An HTTP server you deploy that exposes one or more sources |
| Source | An adapter that translates an upstream API into Alethia's format |
| Upstream | The actual content provider (MangaDex, Komga, etc.) |
| Slug | A unique identifier string used in URLs to fetch specific resources (see Slugs) |
Request Flow
When a user searches for manga, here's what happens:
Your host acts as an adapter, converting upstream data formats into the consistent JSON schema Alethia expects.
Data Flow
Content flows through several stages from upstream to the user:
What You Transform
| Upstream Data | → | Alethia Schema |
|---|---|---|
| Manga details | → | Manga object |
| Search results | → | Entry[] array |
| Chapter list | → | Chapter[] array |
| Page images | → | string[] URLs |
Host Structure
Below is a summary of the required endpoints your host must implement:
| Endpoint | Method | Purpose |
|---|---|---|
/ | GET | Host manifest and available sources |
/:source | GET | Source configuration |
/:source/health | GET | Source health check |
/:source/ping | GET | Upstream connectivity check |
/:source/authenticate | POST | Authentication (if required) |
/:source/search | POST | Search for manga |
/:source/:mangaSlug | GET | Manga details |
/:source/:mangaSlug/chapters | GET | Chapter list |
/:source/:mangaSlug/chapters/:chapterSlug | GET | Page image URLs |
Implementation Overview
You can implement a host in any language. The only requirement is that your responses match the expected JSON schemas.
Deployment Options
Your host can run anywhere that serves HTTP:
- Serverless: Cloudflare Workers, Vercel, AWS Lambda
- Containers: Docker, Kubernetes, Fly.io
- Traditional: VPS, dedicated server, home server
- Local: For personal use with local media servers
Quick Start
- Choose your stack — Any language/framework that can serve HTTP
- Implement endpoints — Start with
/and/:source - Add search — Implement
POST /:source/search - Add content — Implement manga, chapters, and pages endpoints
- Deploy — Host it somewhere accessible
- Test — Add your host URL in Alethia
Documentation
Configuration
Source metadata and capabilities
Endpoints
Detailed endpoint documentation
Schemas
JSON request and response formats
Hosting
Deployment options and best practices
Guidelines
Community and affiliation policies
Example Response
Here's what a minimal search response looks like:
// POST /mangadex/search
// Request: { "query": "one piece", "page": 1, "sort": "relevance" }
{
"results": [
{
"slug": "one-piece-abc123",
"title": "One Piece",
"cover": "https://example.com/cover.jpg"
},
{
"slug": "one-piece-abc124",
"title": "One Piece 2",
"cover": "https://example.com/cover2.jpg"
},
...
],
"page": 1,
"more": true
}The full details are fetched when a user taps on a result:
// GET /mangadex/one-piece-abc124
{
"slug": "one-piece-abc124",
"url": "https://mangadex.org/title/...",
"title": "One Piece",
"alternativeTitles": ["ワンピース"],
"authors": ["Oda Eiichiro"],
"synopsis": "...",
"covers": ["https://..."],
"tags": ["action", "adventure"],
"classification": "Safe",
"publication": "Ongoing",
"createdAt": "2020-01-15T00:00:00Z",
"updatedAt": "2024-12-01T00:00:00Z"
}Read more about the exact schema definitions here:
Schemas
JSON request and response formats