gaetan/knowledgify

Decision: Tech stack — Go framework and frontend approach #9

New issue

Closed

opened 2026-08-20 14:35:02 +02:00 by gaetan · 1 comment

gaetan commented

2026-08-20 14:35:02 +02:00

Owner

Part of #1

Question

Which Go framework and frontend approach should we use?

The content model and user model are settled, so we can now choose the tech stack.

Backend framework options:

net/http (stdlib) — Zero dependencies. Go 1.22+ ServeMux handles path params and wildcards. Pair with encoding/json/v2 for JSON. Simplest possible. Best for a small project.
Chi — Minimal router (~1000 LOC). 100% net/http compatible. Route groups, middleware composition. No built-in JSON binding or rendering — you bring your own.
Gin — Most popular Go web framework. Rich built-in features (JSON binding, validation, middleware, error handling). Custom gin.Context (not net/http compatible). Heavier.

Frontend approach:

Server-rendered HTML (Go templates) — No build step, no JS framework. Simple, fast, works everywhere. Go templates are built into the stdlib. Best for a small personal app.
Go templates + Alpine.js — Server-rendered HTML with lightweight JS for interactivity (flashcard flip, rating buttons). Alpine.js is ~10KB, no build step.
Go backend + SPA (React/Vue/Svelte) — Full SPA. More complex (build step, API layer, state management). Overkill for a single-user study tool.
Go backend + HTMX — Server-rendered HTML with HTMX for interactivity (AJAX, animations). No JS framework, no build step. Growing ecosystem.

Recommended combinations:

net/http + Go templates — Zero dependencies, zero build step. Simplest path.
Chi + Go templates + Alpine.js — Slightly more structure, lightweight interactivity.
Chi + Go templates + HTMX — Server-rendered with AJAX interactivity.

This decision shapes everything: how we serve pages, how we handle API calls, how the review screen works.

Dependencies

Depends on: #2 (content model — shapes API design), #6 (user model — no auth simplifies everything)

Part of #1 ## Question Which Go framework and frontend approach should we use? The content model and user model are settled, so we can now choose the tech stack. Backend framework options: - **net/http (stdlib)** — Zero dependencies. Go 1.22+ ServeMux handles path params and wildcards. Pair with `encoding/json/v2` for JSON. Simplest possible. Best for a small project. - **Chi** — Minimal router (~1000 LOC). 100% net/http compatible. Route groups, middleware composition. No built-in JSON binding or rendering — you bring your own. - **Gin** — Most popular Go web framework. Rich built-in features (JSON binding, validation, middleware, error handling). Custom gin.Context (not net/http compatible). Heavier. Frontend approach: - **Server-rendered HTML (Go templates)** — No build step, no JS framework. Simple, fast, works everywhere. Go templates are built into the stdlib. Best for a small personal app. - **Go templates + Alpine.js** — Server-rendered HTML with lightweight JS for interactivity (flashcard flip, rating buttons). Alpine.js is ~10KB, no build step. - **Go backend + SPA (React/Vue/Svelte)** — Full SPA. More complex (build step, API layer, state management). Overkill for a single-user study tool. - **Go backend + HTMX** — Server-rendered HTML with HTMX for interactivity (AJAX, animations). No JS framework, no build step. Growing ecosystem. Recommended combinations: 1. **net/http + Go templates** — Zero dependencies, zero build step. Simplest path. 2. **Chi + Go templates + Alpine.js** — Slightly more structure, lightweight interactivity. 3. **Chi + Go templates + HTMX** — Server-rendered with AJAX interactivity. This decision shapes everything: how we serve pages, how we handle API calls, how the review screen works. ## Dependencies - Depends on: #2 (content model — shapes API design), #6 (user model — no auth simplifies everything)

gaetan added the

wayfinder:grilling

label

2026-08-20 14:35:02 +02:00

gaetan added a new dependency

2026-08-20 14:35:10 +02:00

#2 Decision: Content model — structure of culture générale cards and categories

gaetan added a new dependency

2026-08-20 14:35:10 +02:00

#6 Decision: User model — single user vs multi-user with auth

gaetan referenced this issue

2026-08-20 14:35:59 +02:00

Decision: Card review UI — how the review screen works #11

gaetan added a new dependency

2026-08-20 14:36:07 +02:00

#11 Decision: Card review UI — how the review screen works

gaetan referenced this issue

2026-08-20 14:36:24 +02:00

Decision: Dashboard and stats — what the user sees outside review #12

gaetan added a new dependency

2026-08-20 14:36:30 +02:00

#12 Decision: Dashboard and stats — what the user sees outside review

gaetan commented

2026-08-20 14:46:32 +02:00

Author

Owner

Resolution

Tech stack decided:

Backend: net/http (stdlib). Go 1.22+ ServeMux for routing (path params, wildcards). No framework dependency. Add chi/middleware only for recovery and logger if desired.

Frontend: Go templates + Alpine.js. Server-rendered HTML base with Alpine.js for interactivity (flashcard flip, rating buttons without page reload, keyboard shortcuts). No build step, no JS framework.

Why not HTMX: Alpine is simpler for this use case — we're manipulating a few DOM elements (flip card, show rating, update progress bar), not doing complex AJAX flows.

Why not SPA: Overkill. Build step, state management, API layer. Single-user study tool.

Why not Gin: Custom gin.Context locks you in. Overkill for a personal app.

File structure:

cmd/knowledgify/
  main.go          # entry point, server setup
internal/
  config/          # config (db path from env)
  content/         # JSON loading, card parsing
  database/        # SQLite setup, migrations
  review/          # review logic, SRS scheduling
  web/
    handlers/      # HTTP handlers
    templates/     # Go HTML templates
    static/        # Alpine.js (pulled from CDN), CSS
pkg/               # public API (if any)
content/           # JSON card files (source of truth)
knowledgify.db     # SQLite database (generated)

## Resolution Tech stack decided: **Backend**: net/http (stdlib). Go 1.22+ ServeMux for routing (path params, wildcards). No framework dependency. Add chi/middleware only for recovery and logger if desired. **Frontend**: Go templates + Alpine.js. Server-rendered HTML base with Alpine.js for interactivity (flashcard flip, rating buttons without page reload, keyboard shortcuts). No build step, no JS framework. **Why not HTMX**: Alpine is simpler for this use case — we're manipulating a few DOM elements (flip card, show rating, update progress bar), not doing complex AJAX flows. **Why not SPA**: Overkill. Build step, state management, API layer. Single-user study tool. **Why not Gin**: Custom gin.Context locks you in. Overkill for a personal app. **File structure**: ``` cmd/knowledgify/ main.go # entry point, server setup internal/ config/ # config (db path from env) content/ # JSON loading, card parsing database/ # SQLite setup, migrations review/ # review logic, SRS scheduling web/ handlers/ # HTTP handlers templates/ # Go HTML templates static/ # Alpine.js (pulled from CDN), CSS pkg/ # public API (if any) content/ # JSON card files (source of truth) knowledgify.db # SQLite database (generated) ```

gaetan closed this issue

2026-08-20 14:46:36 +02:00

gaetan referenced this issue

2026-08-20 14:47:37 +02:00

Wayfinder map: Anki-like spaced repetition web app for culture générale #1

gaetan referenced this issue

2026-08-20 14:50:10 +02:00

Decision: Tech stack — Go web framework and frontend approach #4