space-aditya/go_todo

1. Overall shape

- This is a two-tier todo application: a Go backend serves both the API and the built frontend assets, and a React/Vite SPA provides the UI.

- Persistent state is stored in PostgreSQL in production, with an in-memory store available for simpler or test-style execution.

2. Backend entrypoint and runtime

- The server starts from cmd/server/main.go.

- The backend is a single Go process that owns HTTP routing, middleware, request handling, store selection, and static asset serving.

3. HTTP/API boundary

- internal/handler contains the HTTP layer for todo operations.

- This layer translates incoming requests into store calls and returns JSON/error responses; it is the boundary between transport concerns and domain/storage concerns.

4. Middleware boundary

- internal/middleware holds cross-cutting HTTP behavior.

- This is where request-level concerns such as logging, recovery, CORS, or similar wrapping behavior are centralized rather than duplicated in handlers.

5. Domain model

- internal/model defines the core todo types and application errors.

- The todo model is the shared contract between handlers, stores, and the frontend API shape.

6. Storage abstraction

- internal/store/store.go defines the store interface used by the handlers.

- There are two concrete implementations:

- internal/store/memory.go for an in-process, non-persistent backend

- internal/store/postgres.go for production persistence

7. Persistence path

- In the PostgreSQL path, handlers call the store interface, which executes SQL against the database.

- The schema is managed separately under migrations/, with at least one migration creating the todos table.

8. Frontend application

- internal/frontend is a full React 19 + Vite application, with source under src/ and a production build in dist/.

- The frontend is componentized into form/list/item pieces and uses a custom hook plus API module to fetch and mutate todos.

9. Frontend-to-backend data flow

- The React app does not talk to the database directly.

- It calls backend HTTP endpoints through internal/frontend/src/api/todos.ts, and state is orchestrated in useTodos.ts, then rendered by App.tsx and the todo components.

10. Frontend asset embedding

- internal/frontend_embed.go indicates the built frontend is embedded into the Go binary.

- This means the same backend process can serve the SPA assets in production without a separate static server.

11. Deployment model

- Dockerfile uses a multi-stage build: it builds the frontend, compiles the Go server, and packages both together.

- docker-compose.yml wires the app together with PostgreSQL for a production-like local environment.

12. Configuration and environment

- The README notes the backend is driven by environment variables such as DATABASE_URL, LISTEN_ADDR, and APP_ENV.

- That suggests the runtime behavior changes based on deployment context, especially store selection and server binding.

13. Testing boundaries

- Tests exist for handlers, middleware, model, and both store implementations.

- This implies clear separation of concerns: HTTP behavior, domain validation/error handling, and persistence logic are each testable in isolation.

14. Diagram-worthy summary

- The key architecture diagram should show: browser SPA → Go HTTP handlers → store interface → Postgres or memory store → database, with middleware wrapping the HTTP layer and embedded frontend assets served from the same backend process.