Files

45 lines
3.0 KiB
Markdown

# Agents.md
## Project Context
**readeckobo** is a proxy server written in Go. Its primary purpose is to act as a bridge between **Kobo e-readers** and a self-hosted **Readeck** instance.
Kobo e-readers have built-in support for **Instapaper**. This application emulates the Instapaper API so that Kobo devices can sync articles from Readeck seamlessly, without requiring custom firmware on the device.
## Architecture Overview
The project follows a standard Go project layout:
- **`cmd/readeckobo/`**: Entry point (`main.go`). Initializes configuration, logger, and starts the server.
- **`internal/app/`**: Core business logic. Contains handlers for the Kobo (Instapaper) API endpoints (`/api/1/oauth/access_token`, `/api/1/bookmarks/list`, etc.) and image conversion logic.
- **`internal/readeck/`**: Client implementation for communicating with the Readeck API. Handles authentication and data fetching.
- **`internal/webserver/`**: HTTP server setup, routing, and middleware.
- **`internal/config/`**: Configuration management using `koanf`.
- **`internal/models/`**: Shared data structures for Kobo and Readeck API payloads.
## Deployment & Infrastructure
- **Deployment**: Kobo requests can reach this app through Cloudflare Tunnel or Nginx. See `docs/CLOUDFLARE.md` and `docs/NGINX.md` for the routing and initialization rewrite examples.
- **Docker**: The application is containerized (`Dockerfile`, `docker-compose.yml`).
## Development Guidelines for AI Agents
### 1. Code Style & Conventions
- Follow standard Go idioms (Effective Go).
- **No external mock libraries**: Use manual mocking strategies (e.g., `MockRoundTripper` in `internal/app/app_test.go`) rather than introducing dependencies like `mockgen` or `testify` unless explicitly requested.
- Use **Table-Driven Tests** for unit testing logic.
### 2. Testing Protocol
- **Unit Tests**: Required for all logic changes.
- Location: `*_test.go` files next to the code.
- pattern: Mock external HTTP calls to Readeck or Kobo to ensure isolation.
- **E2E Tests**: `scripts/e2e-tests/` contains shell scripts for manual human verification.
- Agents should be aware of these flows but are not expected to run them autonomously unless the environment is fully configured (which is rare in a CLI session).
- Agents *should* maintain the validity of these scripts if endpoint signatures change.
### 3. Key Dependencies & Logic
- **Image Conversion**: Kobo devices often require specific image formats (JPEG, grayscale optimizations). This logic resides in `internal/app`.
- **API Emulation**: The application strictly adheres to the Instapaper API format expected by Kobo devices.
- *Constraint*: Do not change the JSON structure of responses sent to Kobo, as the device firmware is brittle.
### 4. Refactoring & Maintenance
- When refactoring, ensure strict separation between the `webserver` (transport layer) and `app` (business logic).
- Configuration changes in `config.yaml` or `internal/config` must be reflected in `config.yaml.example`.