45 lines
3.0 KiB
Markdown
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`.
|