[Architecture] Feature — Exportable Provider Interface (Library Architecture)

[0xheartcode]

Overview

gh-dash puts all of its code in internal/, which means no other Go project can import any of it. lazydash has an opportunity to be different from day one by structuring the project so the data layer is exported and the TUI layer is private, making lazydash both a standalone terminal app AND a reusable Go library.

Current State

All code is in a flat structure with no exported provider interface. Other Go projects cannot import lazydash's data-fetching logic.

Proposed Solution

Separate the project into exported (public) packages for data access and private packages for the TUI:

lazydash/
  provider/
    provider.go          -- interface definition + shared types (EXPORTED)
    github/
      github.go          -- GitHub implementation (EXPORTED)
  cache/
    cache.go             -- local storage/search (EXPORTED)
  internal/
    tui/                 -- bubbletea UI code (PRIVATE)
    config/              -- config parsing internals (PRIVATE)
  cmd/
    root.go
    search.go
  main.go

The provider.go file defines a contract:

type Provider interface {
    FetchProjects(ctx context.Context) ([]Project, error)
    FetchBoardView(ctx context.Context, projectID string) (*BoardView, error)
    FetchItems(ctx context.Context, projectID string) ([]Item, error)
    SearchItems(ctx context.Context, query string) ([]Item, error)
}

Shared data types (Project, Item, BoardView, Column, Card) live in the provider package and are provider-agnostic.

Why This Matters

This is the single most important architectural decision to get right early. Once you export a type, you cannot casually rename it without breaking other people's builds. Keep exported types small and stable at first, use internal/ for anything experimental, and promote things to exported status only when confident in the design.

Priority

Do first. This is the foundation everything else builds on.

Recommended Build Order (for reference)

1. Provider interface + project structure (this issue)
2. Offline cache (#next) + local search/recall + context-aware repo scoping
3. Issue detail view
4. Fullscreen/zen mode
5. Verbose/debug mode
6. Offline notes
7. Multi-provider support
8. pkg.go.dev docs
9. Scriptable batch operations
10. Online write support

Acceptance Criteria

• provider/provider.go defines the Provider interface with FetchProjects, FetchBoardView, FetchItems, SearchItems
• Shared types (Project, Item, BoardView, Column, Card) are in the provider package
• provider/github/github.go implements the interface using gh CLI / GraphQL
• TUI code lives in internal/tui/
• External Go code can import and use the provider package

Epic: This is an epic-sized issue that will need to be broken down into smaller sub-issues when work begins.

[0xheartcode]

🏗️ Epic Notice

This is an epic-sized issue — it represents a significant architectural change (restructuring the entire project layout, defining the core interface contract, migrating existing code). It will need to be broken down into smaller, individually-mergeable sub-issues when work begins. Suggested breakdown:

1. Define Provider interface and shared types in provider/provider.go
2. Create provider/github/ implementation wrapping existing GraphQL logic
3. Move TUI code into internal/tui/
4. Move config code into internal/config/
5. Update cmd/ to wire everything together
6. Add integration tests for the provider package

Recommended Build Order (Full Roadmap)

For reference, the recommended sequencing across all roadmap issues:

1. Provider interface + project structure (this issue, [Architecture] Feature — Exportable Provider Interface (Library Architecture) #15)
2. Offline cache ([CLI] Feature — Offline Browsing via Local Cache #17) + Local search/recall ([CLI] Feature — Local Search and Recall #18) + Context-aware search ([CLI] Feature — Context-Aware Search (Current Repo as Default Scope) #25)
3. Issue detail view ([TUI] Feature — Dedicated Issue/Item Detail View #21)
4. Fullscreen/zen mode ([TUI] Feature — Fullscreen / Zen Mode Toggle #20)
5. Verbose/debug mode ([CLI] Feature — Verbose / Debug Mode #26)
6. Offline notes ([TUI] Feature — Offline Notes on Issues #19)
7. Multi-provider support ([Architecture] Feature — Multi-Provider Support (GitLab, Gitea, etc.) #16)
8. pkg.go.dev docs ([Docs] Feature — pkg.go.dev Documentation #24)
9. Scriptable batch operations ([CLI] Feature — Scriptable Batch Operations #22)
10. Online write support ([API] Feature — Online Write Support (Commenting, Editing, State Changes) #23)
11. Self-update — already tracked in [CLI] Feature — Add lazydash version and lazydash update commands #13