111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
Mangarr is a Symfony 7.0 manga management/reader application. It scrapes manga chapters from various sources, stores them as CBZ files, and provides a reader interface. It runs on FrankenPHP inside Docker.
|
|
|
|
## Common Commands
|
|
|
|
All commands run via Docker through the Makefile. Use `make help` to see all available targets.
|
|
|
|
```bash
|
|
make start # Start Docker containers
|
|
make stop # Stop containers
|
|
make install # Build images, start containers, install deps (first-time setup)
|
|
make logs # Follow container logs
|
|
make sh # Shell into the PHP container
|
|
```
|
|
|
|
**PHP / Symfony:**
|
|
```bash
|
|
make sf c="about" # Run any Symfony console command
|
|
make cc # Clear cache
|
|
make vendor # Install Composer dependencies
|
|
make migration-migrate # Run pending migrations
|
|
make fixtures-load # Load fixtures (drops and recreates data)
|
|
```
|
|
|
|
**Testing:**
|
|
```bash
|
|
make test # Run all tests
|
|
make test f="ScrapeChapterHandlerTest" # Run a specific test by class name
|
|
make test c="--group e2e" # Pass phpunit options
|
|
```
|
|
|
|
**Code Quality:**
|
|
```bash
|
|
make phpcs # Fix code style (PSR-12 via php-cs-fixer)
|
|
make phpmd # Run PHP Mess Detector
|
|
make quality # Run both phpmd and phpcs
|
|
make phparkitect # Check architectural rules
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
make npm-run # Build assets once (dev)
|
|
make npm-watch # Watch and rebuild assets
|
|
make npm-add p=pkg # Add an npm dependency
|
|
```
|
|
|
|
**Messenger workers** (run in separate terminals):
|
|
```bash
|
|
make consume-commands # Process command.bus messages
|
|
make consume-events # Process domain events
|
|
make consume-schedule # Process scheduled tasks
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The project uses **Domain-Driven Design** with strict layer separation enforced by PHPArkitect (`phparkitect.php`).
|
|
|
|
### Domain Structure
|
|
|
|
```
|
|
src/Domain/
|
|
{DomainName}/
|
|
Domain/ # Pure domain: Models, Contracts (interfaces), Events, Exceptions
|
|
Application/ # Use cases: Commands, Queries, CommandHandlers, QueryHandlers, Responses
|
|
Infrastructure/ # Framework: Persistence, API Platform State, Clients, Services
|
|
Shared/ # Cross-domain contracts and infrastructure (MangaPathManagerInterface, EventDispatcherInterface, etc.)
|
|
```
|
|
|
|
**Business domains:** `Manga`, `Reader`, `Scraping`, `Conversion`, `Setting` (+ `Shared`)
|
|
|
|
**Architectural rules enforced:**
|
|
- `Domain` layer has no outside dependencies (only std exceptions)
|
|
- `Application` layer may depend on its own Domain + `App\Domain\Shared\Domain\Contract` + `Symfony\Messenger` + `Ramsey\Uuid`; never on Infrastructure
|
|
- `Shared` depends on nothing outside itself
|
|
|
|
### Outside Domain (`src/`)
|
|
|
|
- `src/Entity/` — Doctrine ORM entities (legacy, used by repositories)
|
|
- `src/Controller/` — Symfony HTTP controllers
|
|
- `src/ApiResource/` — API Platform resource definitions + `OpenApiFactoryDecorator`
|
|
- `src/Service/` — Legacy services (being migrated into Domain)
|
|
- `src/Message/` + `src/MessageHandler/` — Legacy Messenger messages (outside DDD)
|
|
|
|
### Frontend
|
|
|
|
- `assets/controllers/` — Stimulus controllers (one per UI interaction)
|
|
- `assets/vue/app/` — Vue.js SPA mounted at `/vue/*`
|
|
- Tailwind CSS via PostCSS, bundled with Webpack Encore
|
|
- Mercure for real-time updates (queue status, download progress)
|
|
|
|
### Key Infrastructure
|
|
|
|
- **Database:** PostgreSQL 16 via Doctrine ORM; Adminer on port 8080
|
|
- **Scraping:** `scrapers.json` defines per-site CSS selectors; `HtmlScraper` and `JavascriptScraper` (Panther) strategies
|
|
- **File storage:** CBZ files stored at `MANGA_DATA_PATH` (default `~/Mangas`); images at `IMAGE_DATA_PATH`
|
|
- **External API:** MangaDex client for metadata (`MANGADEX_CLIENT_ID/SECRET/USERNAME/PASSWORD` env vars)
|
|
- **Messenger buses:** `command.bus` (sync commands), `events` transport, `commands` transport, `async` transport (scheduler)
|
|
|
|
### Adding a New Domain Feature
|
|
|
|
1. Define contracts (interfaces) in `Domain/{Name}/Domain/Contract/`
|
|
2. Write Command/Query + Handler in `Domain/{Name}/Application/`
|
|
3. Implement interfaces in `Domain/{Name}/Infrastructure/`
|
|
4. Register infrastructure aliases in `config/services.yaml`
|
|
5. Run `make phparkitect` to validate layer boundaries
|