Foundation roadmap for Bookshelf v0.1.x

[Gdetrane]

Summary

Bookshelf already has a strong prototype core: a single Go binary, embedded Vue frontend, simple SQLite-backed state, and a clean enough architecture to keep building on.

After a thorough review, I think we can make it much easier to maintain and extend if we align on a small set of foundation decisions before feature scope grows too much.

The main goal of this issue is to agree on the initial roadmap for v0.1.x, especially around documentation, CI/security, database support, packaging, and the backend changes needed to support future formats and clients cleanly.

Why now

This project is still early enough that we can fix the high-leverage foundations now without a painful rewrite later.

A few things already stand out:

• The overall architecture is promising and worth keeping.
• The current backend identity model is too path-centric for long-term sync/progress/client support.
• PDF assumptions are spread through the stack, which is fine for a draft but not for future EPUB/CBZ/etc.
• Frontend unit-test coverage is effectively absent.
• Backend tests exist, but are concentrated mostly around API handlers.
• There is currently no real CI/CD/release/security baseline in-repo.
• Human-facing documentation should move to docs/, while spec/ can stay focused on spec-driven/planning artifacts.
• The repo is not yet agent-ready by the standards I want us to support.

Key findings from review

Backend / architecture

• The Go backend is structured reasonably well: cmd/, internal/api, internal/store, internal/scanner, internal/pdfstream, internal/web.
• The main architectural pressure point is that books are currently identified by relative path, which will make file moves, deduplication, sync, and future client support harder.
• Content serving should eventually become catalog-aware instead of serving filesystem paths directly.
• Format support should become explicit in the data model instead of assuming PDF everywhere.

Frontend / testing

• Vue structure is decent for a first version, but quality gates are minimal.
• There are currently no frontend unit tests or frontend test scripts.
• A few route/reactivity issues likely deserve attention early.

Delivery / release engineering

• No GitHub Actions workflows are currently present.
• No releases or tags yet.
• Docker packaging foundation is good, but we should formalize CI, release automation, and deployment assets.

Proposed roadmap

1. First PR: agent-readiness and docs baseline

Keep the first PR intentionally small and docs-focused.

Scope:

• add root AGENTS.md
• add root ARCHITECTURE.md
• add root CONTRIBUTING.md
• improve README.md
• move durable human-facing docs into docs/
• add .github/CODEOWNERS

I think this is the best first PR because it is low-risk and immediately improves contributor/agent ergonomics.

2. CI / security / release baseline

Add GitHub Actions before larger refactors.

Baseline CI:

• Go tests
• race tests
• go vet
• frontend install + typecheck + build
• container build smoke test

Security / compliance baseline:

• govulncheck
• Trivy
• secret scanning
• actionlint
• hadolint
• Dependabot for:
  • Go modules
  • npm
  • Docker
  • GitHub Actions

Later, once chart/manifests exist:

• yamllint
• helm lint
• kubeconform
• optional CodeQL

Release expectations:

• semantic versioning starting around v0.1.0
• GHCR image publishing
• SBOM + provenance attestations
• release binaries for:
  • Linux amd64, arm64
  • macOS amd64, arm64
  • Windows amd64, arm64

3. Test coverage work

Backend:

• expand beyond API tests into store/scanner/content-serving packages
• aim for very high coverage in small critical packages

Frontend:

• add Vitest + Vue Test Utils + coverage
• start with composables and API utilities
• then targeted component/page tests

I would not enforce 100% coverage on the TS side initially.

4. Backend foundation refactor before scope growth

Before adding more formats or sync features, I think we should address:

• stable internal book identity instead of path-only identity
• catalog-aware content serving
• explicit format/content metadata
• transactional collection operations
• clearer upload/deployment contract
• storage/repository layer that supports both SQLite and PostgreSQL cleanly

This is not a rewrite, but I do think it is worth doing early.

5. Packaging / deployment assets

Add:

• docker-compose
• Helm chart
• ArgoCD-oriented docs/examples

I want the chart to support both database modes clearly:

SQLite mode

• simplest self-hosted path
• single replica
• PVC-backed DB

PostgreSQL mode

• external PostgreSQL
• in-cluster PostgreSQL via CloudNativePG

The chart should make both easy to understand and easy to configure.

6. Near-term product scope

For the first releases, I’d keep scope intentionally small:

• excellent PDF experience
• remote reading that works well over Tailscale/private networks
• strong progress/bookmark/note correctness
• good docs and contributor ergonomics
• solid packaging and deployment

Then expand toward:

• EPUB/CBZ/CBR
• syncable reading progress
• mobile/desktop-friendly API evolution
• OPDS-compatible catalog/export for eInk/mobile interoperability
• richer caching/performance improvements

Decisions I’d like us to align on

1. Should we treat docs/ as the home for human-facing docs and keep spec/ for planning/spec artifacts?
2. Do we want SQLite-only for now, or do we agree to make SQLite + PostgreSQL both first-class?
3. Is a docs/agent-readiness first PR the right starting point?
4. Should the Helm chart support both external Postgres and CloudNativePG from the start?
5. Are we aligned on a stronger CI/security baseline early, including Dependabot and vulnerability scanning?
6. Do we want to formally target remote/Tailscale-first private deployments in early docs?

Suggested initial PR sequence

1. docs: agent readiness baseline
2. ci: go/web verify + security scanning + dependabot + release scaffolding
3. test: frontend test harness + broader backend coverage
4. fix: harden content serving + clarify upload/deploy contract
5. refactor: stable identity + DB portability + format abstraction
6. deploy: compose + Helm + ArgoCD docs
7. feat: first non-PDF format support

Closing thought

I think Bookshelf has the right shape to become a genuinely excellent self-hosted reading platform, but the leverage right now is in getting the foundation and operational story right before feature scope expands.

If this roadmap looks reasonable, I can start with the first PR around docs + agent-readiness.

[Gdetrane]

@sovietspaceship ptal

[Gdetrane]

@sovietspaceship emphasis on the OPDS spec when we will expand in the future, maybe this is the key to having support for native clients in eReaders (probably not Kindle, not sure how that could handle Tailscale), but maybe android based ones.

Haven't checked this spec entirely yet, but should be relevant