melosh/mal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align README markdown tables

Browse Source
This commit is contained in:
mkelvers
2026-06-21 16:52:19 +02:00
committed by Milas Holsting
parent 4bb9caa972
commit fb8433a435
1 changed files with 59 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
README.md
View File

@@ -28,9 +28,8 @@ part of the project is the product shape: server-rendered pages, a local databas
integrations, playback proxying, recommendations, migrations, tests, and a TypeScript player that integrations, playback proxying, recommendations, migrations, tests, and a TypeScript player that
only appears where browser state actually earns its place. only appears where browser state actually earns its place.
> [!NOTE] > [!NOTE] This is a personal, local-first project. It is written to demonstrate product engineering
> This is a personal, local-first project. It is written to demonstrate product engineering choices, > choices, not to present itself as an official MyAnimeList client or a hosted streaming platform.
> not to present itself as an official MyAnimeList client or a hosted streaming platform.
## Contents ## Contents
@@ -59,15 +58,15 @@ the edges, and the UI is mostly rendered by the server.
## What It Includes ## What It Includes
| Area | What it does | | Area | What it does |
| --- | --- | | --------------- | ------------------------------------------------------------------------------------------------------------ |
| Catalog | Browse, search, and inspect anime metadata from external catalog sources. | | Catalog | Browse, search, and inspect anime metadata from external catalog sources. |
| Details | Render synopsis, reviews, characters, statistics, relations, themes, and watch-order data. | | Details | Render synopsis, reviews, characters, statistics, relations, themes, and watch-order data. |
| Watchlist | Store local user state for saved titles, statuses, and progress-driven flows. | | Watchlist | Store local user state for saved titles, statuses, and progress-driven flows. |
| Playback | Serve watch pages, proxy streams/subtitles, rewrite playlists, and track progress. | | Playback | Serve watch pages, proxy streams/subtitles, rewrite playlists, and track progress. |
| Player | Handle HLS playback, quality selection, subtitles, keyboard controls, episode navigation, and skip segments. | | Player | Handle HLS playback, quality selection, subtitles, keyboard controls, episode navigation, and skip segments. |
| Recommendations | Generate personal top picks from watchlist signals and recommendation data. | | Recommendations | Generate personal top picks from watchlist signals and recommendation data. |
| Maintenance | Run migrations, startup fixes, local user commands, and data repair scripts. | | Maintenance | Run migrations, startup fixes, local user commands, and data repair scripts. |
<details> <details>
<summary><strong>Implementation notes</strong></summary> <summary><strong>Implementation notes</strong></summary>
@@ -85,10 +84,11 @@ segments, episode completion, and thumbnail navigation.
## How It Is Built ## How It Is Built
The application is organized around product boundaries rather than framework layers. `internal/anime` The application is organized around product boundaries rather than framework layers.
owns catalog-facing behavior, `internal/watchlist` owns saved user state, `internal/playback` owns `internal/anime` owns catalog-facing behavior, `internal/watchlist` owns saved user state,
watch data and proxy behavior, and `integrations` contains provider clients. This keeps the core app `internal/playback` owns watch data and proxy behavior, and `integrations` contains provider
from depending directly on the details of a specific metadata or playback source. clients. This keeps the core app from depending directly on the details of a specific metadata or
playback source.
Server-rendered templates are the default because most pages are content-heavy and benefit from Server-rendered templates are the default because most pages are content-heavy and benefit from
simple request-response rendering. TypeScript is used where the browser has real ongoing state: simple request-response rendering. TypeScript is used where the browser has real ongoing state:
@@ -110,8 +110,8 @@ bun install
just dev just dev
``` ```
The development server runs on `http://localhost:3000` by default. `just dev` uses Air to rebuild the The development server runs on `http://localhost:3000` by default. `just dev` uses Air to rebuild
Go server and frontend assets when relevant files change. the Go server and frontend assets when relevant files change.
Create a local user with: Create a local user with:
@@ -121,64 +121,64 @@ go run ./cmd/user <username> <password>
### Commands ### Commands
| Command | Use it for | | Command | Use it for |
| --- | --- | | ------------------------------- | --------------------------------------------------- |
| `just setup` | Install pinned tools and Bun dependencies. | | `just setup` | Install pinned tools and Bun dependencies. |
| `just dev` | Run the app locally with live rebuilds. | | `just dev` | Run the app locally with live rebuilds. |
| `just build` | Build the Go binary, CSS, and TypeScript assets. | | `just build` | Build the Go binary, CSS, and TypeScript assets. |
| `just test` | Run the Go test suite. | | `just test` | Run the Go test suite. |
| `just check` | Run linting, tests, typechecking, and a full build. | | `just check` | Run linting, tests, typechecking, and a full build. |
| `just lint-go` / `just lint-ts` | Run backend or frontend linting separately. | | `just lint-go` / `just lint-ts` | Run backend or frontend linting separately. |
| `just typecheck` | Run TypeScript without emitting files. | | `just typecheck` | Run TypeScript without emitting files. |
| `just run` | Build and run the compiled server. | | `just run` | Build and run the compiled server. |
| `just clean` | Remove generated build output. | | `just clean` | Remove generated build output. |
<details> <details>
<summary><strong>Configuration</strong></summary> <summary><strong>Configuration</strong></summary>
Configuration is loaded from environment variables, and a local `.env` file is read automatically. Configuration is loaded from environment variables, and a local `.env` file is read automatically.
| Variable | Default | Purpose | | Variable | Default | Purpose |
| --- | --- | --- | | --------------------------- | --------------- | ------------------------------------------------------------------- |
| `PORT` | `3000` | HTTP port for the server. | | `PORT` | `3000` | HTTP port for the server. |
| `DATABASE_FILE` | `mal.db` | SQLite database path. | | `DATABASE_FILE` | `mal.db` | SQLite database path. |
| `GIN_MODE` | release default | Gin runtime mode. | | `GIN_MODE` | release default | Gin runtime mode. |
| `MAL_CORS_ALLOW_ALL` | disabled | Allows any origin when set to `1`; intended for local/proxy setups. | | `MAL_CORS_ALLOW_ALL` | disabled | Allows any origin when set to `1`; intended for local/proxy setups. |
| `PLAYBACK_PROXY_SECRET` | empty | Enables signed playback proxy tokens when set. | | `PLAYBACK_PROXY_SECRET` | empty | Enables signed playback proxy tokens when set. |
| `EPISODE_AVAILABILITY_MODE` | `auto` | Episode availability strategy: `auto`, `legacy`, or `jikan`. | | `EPISODE_AVAILABILITY_MODE` | `auto` | Episode availability strategy: `auto`, `legacy`, or `jikan`. |
| `MAL_JIKAN_TRACE` | disabled | Enables optional Jikan client tracing when truthy. | | `MAL_JIKAN_TRACE` | disabled | Enables optional Jikan client tracing when truthy. |
</details> </details>
<details> <details>
<summary><strong>Maintenance commands</strong></summary> <summary><strong>Maintenance commands</strong></summary>
| Command | Use it for | | Command | Use it for |
| --- | --- | | ------------------------ | ---------------------------------------------------------- |
| `just new-data-fix name` | Scaffold a new data-fix file. | | `just new-data-fix name` | Scaffold a new data-fix file. |
| `just run-fixes` | Run registered data fixes through `cmd/user`. | | `just run-fixes` | Run registered data fixes through `cmd/user`. |
| `just fix-all` | Run the Bun maintenance script for data fixes. | | `just fix-all` | Run the Bun maintenance script for data fixes. |
| `bun run format` | Format TypeScript and related frontend files with `oxfmt`. | | `bun run format` | Format TypeScript and related frontend files with `oxfmt`. |
</details> </details>
## Repository Map ## Repository Map
| Path | Responsibility | | Path | Responsibility |
| --- | --- | | -------------------------------- | --------------------------------------------------------------- |
| `cmd/server` | Web server entry point. | | `cmd/server` | Web server entry point. |
| `cmd/user` | Local user and maintenance commands. | | `cmd/user` | Local user and maintenance commands. |
| `internal/anime` | Catalog, details, browse, search, reviews, and recommendations. | | `internal/anime` | Catalog, details, browse, search, reviews, and recommendations. |
| `internal/auth` | Authentication, middleware, and local user handling. | | `internal/auth` | Authentication, middleware, and local user handling. |
| `internal/watchlist` | Watchlist handlers, service logic, and persistence. | | `internal/watchlist` | Watchlist handlers, service logic, and persistence. |
| `internal/playback` | Watch data, progress, proxy tokens, and skip segments. | | `internal/playback` | Watch data, progress, proxy tokens, and skip segments. |
| `internal/episodes` | Episode refresh and provider mapping. | | `internal/episodes` | Episode refresh and provider mapping. |
| `internal/database` | SQLite setup, migrations, and startup data fixes. | | `internal/database` | SQLite setup, migrations, and startup data fixes. |
| `integrations/jikan` | Jikan API client and catalog types. | | `integrations/jikan` | Jikan API client and catalog types. |
| `integrations/playback/allanime` | Playback provider client and extraction logic. | | `integrations/playback/allanime` | Playback provider client and extraction logic. |
| `templates` | Server-rendered pages and reusable components. | | `templates` | Server-rendered pages and reusable components. |
| `static` | TypeScript source for client-side behavior. | | `static` | TypeScript source for client-side behavior. |
| `scripts` | Bun-powered development and maintenance scripts. | | `scripts` | Bun-powered development and maintenance scripts. |
--- ---