80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
# PocketChords
|
|
|
|
A rip-off of [Ultimate Guitar](https://www.ultimate-guitar.com/) with a focus on mobile users, without any ads or subscription. Self-hosted, open source and free to use.
|
|
|
|
## Features
|
|
|
|
- Import chord sheets from Ultimate Guitar URLs or HTML files (bulk import supported)
|
|
- Transpose chords up/down with one tap
|
|
- Piano keyboard and guitar fretboard chord diagrams
|
|
- Capo support with sounding-key display
|
|
- Adjustable font size (S/M/L) for readability while playing
|
|
- Search and sort your library
|
|
- Dark/light theme
|
|
- PWA — add to home screen for native feel
|
|
- JWT auth with registration/login
|
|
- OpenAPI docs at `/docs`
|
|
|
|
## Architecture
|
|
|
|
Hexagonal / ports-and-adapters with CQRS in the application layer. See `architecture.mmd` for the full diagram.
|
|
|
|
```
|
|
crates/
|
|
domain/ # entities, value objects, ports, domain services
|
|
application/ # use cases: songs/, tabs/, auth/ (commands, queries, deps)
|
|
presentation/ # axum HTTP server, routes, extractors, OpenAPI
|
|
api-types/ # request/response DTOs
|
|
infra-wiring/ # shared config (AppConfig)
|
|
adapters/
|
|
sqlite/ # SQLite persistence (songs, users, refresh sessions)
|
|
ug-parser/ # Ultimate Guitar HTML parser
|
|
auth/ # JWT + Argon2 password hashing
|
|
app/ # React Router SPA (Tailwind, shadcn/ui)
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# prerequisites: rust, node
|
|
|
|
# run locally (builds frontend, starts backend on :8000)
|
|
make dev
|
|
|
|
# or backend only (if frontend already built)
|
|
make dev-api
|
|
|
|
# run checks (fmt, clippy, tests)
|
|
make check
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Single Docker image serves both API and SPA:
|
|
|
|
```bash
|
|
# build and push to private registry
|
|
make deploy
|
|
|
|
# or with a specific tag
|
|
./deploy.sh --tag v1.0.0
|
|
```
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Default | Description |
|
|
| ---------------------- | ----------------------------- | ------------------------------ |
|
|
| `DATABASE_URL` | `sqlite://./pocket-chords.db` | SQLite connection string |
|
|
| `HOST` | `0.0.0.0` | Bind address |
|
|
| `PORT` | `8000` | Bind port |
|
|
| `JWT_SECRET` | _(required)_ | Secret for signing JWTs |
|
|
| `JWT_TTL_SECONDS` | `900` | Access token TTL (15 min) |
|
|
| `REFRESH_TTL_SECONDS` | `2592000` | Refresh token TTL (30 days) |
|
|
| `ALLOW_REGISTRATION` | `false` | Enable user registration |
|
|
| `CORS_ALLOWED_ORIGINS` | `*` | Comma-separated origins or `*` |
|
|
| `SPA_DIR` | `./app/build/client` | Path to SPA static files |
|
|
|
|
## License
|
|
|
|
MIT (see [LICENSE](LICENSE) for details).
|