docs: update docs

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## What
+
+_what the PR changes_
+
+## Why
+
+_why these changes were made_
+
+## Test Plan
+
+_how did you verify these changes did what you expected_
+
+## Checklist
+
+- [ ] Tested all changes locally
+- [ ] Updated relevant documentation in `docs/`

docs/Getting Started.md

@@ -0,0 +1,121 @@
+# Getting Started
+
+## Prerequisites
+
+**Required:**
+- [Docker](https://docs.docker.com/get-docker/) - Container runtime
+- [Go 1.25.3+](https://go.dev/doc/install) - For code generation
+- [Make](https://www.gnu.org/software/make/) - Build automation (usually pre-installed on Linux/macOS)
+
+**Optional (for frontend development):**
+- [Node.js 25+](https://nodejs.org/) - For rapid frontend iteration
+
+**New to these technologies?**
+- [Docker Getting Started Guide](https://docs.docker.com/get-started/)
+- [Makefile Tutorial](https://makefiletutorial.com/)
+- [Go by Example](https://gobyexample.com/)
+- [React Tutorial](https://react.dev/learn)
+
+## Quick Start
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd <repository-name>
+   ```
+
+2. **Configure environment**
+   ```bash
+   cp .env.example .env
+   ```
+   Modify as needed for local development.
+
+3. **Build and run**
+   ```bash
+   make build
+   make run
+   ```
+
+4. **Access the application**
+   - Open `http://localhost:8080` in a browser
+   - API available at `http://localhost:8080/api/v1/*`
+
+## Docker-First Development
+
+This project uses Docker for all builds and deployments. The Dockerfile handles:
+- Installing Go dependencies
+- Building the frontend with Node/Vite
+- Copying built frontend to `server/web/`
+- Compiling the Go binary with embedded frontend
+- Creating a minimal runtime image
+
+## Common Commands
+
+All commands are defined in the `Makefile`.
+
+### Build
+```bash
+make build
+```
+Builds the Docker image tagged as `csh-home`. This runs the full build process: frontend compilation, Go code generation, and binary compilation with embedded assets.
+
+### Run
+```bash
+make run
+```
+Runs the containerized application. Loads environment variables from `.env` file and exposes port 8080.
+
+### Generate
+```bash
+make generate
+```
+Runs `go generate ./...` to regenerate `api/gen.go` from `api/openapi.yaml`. **Run this after modifying the OpenAPI specification.**
+
+### Format
+```bash
+make fmt
+```
+Formats all Go code using `go fmt`. Run before committing changes.
+
+### Lint
+```bash
+make lint
+```
+Runs `golangci-lint` for Go code and `npm run lint` for frontend code. Both run in Docker containers.
+
+## Modifying the API
+
+1. Edit `api/openapi.yaml` to add/change endpoints
+2. Run `make generate` to regenerate Go code
+3. Implement handler methods in `api/server_*.go`
+4. Run `make build` to create a new Docker image
+5. Run `make run` to test changes
+
+## Rapid Frontend Development
+
+For faster frontend iteration without rebuilding the Docker image:
+
+1. **Start the backend container**
+   ```bash
+   make run
+   ```
+
+2. **In a new terminal, start the frontend dev server**
+   ```bash
+   cd web
+   npm install
+   npm run dev
+   ```
+
+The Vite dev server runs on `http://localhost:5173` (typically) with hot module reloading. All API requests (`/api/*`) are automatically proxied to the Docker container running the backend at `http://localhost:8080`. This allows rapid frontend changes without rebuilding the entire application.
+
+When frontend work is complete, run `make build` to create a production Docker image with the embedded frontend.
+
+## Useful Resources
+
+- [OpenAPI Specification](https://swagger.io/specification/) - API spec format
+- [Gin Framework Guide](https://gin-gonic.com/docs/) - HTTP framework documentation
+- [oapi-codegen Documentation](https://github.com/oapi-codegen/oapi-codegen) - Code generator
+- [Go embed Package](https://pkg.go.dev/embed) - File embedding
+- [Docker Documentation](https://docs.docker.com/) - Container platform
+- [Vite Guide](https://vitejs.dev/guide/) - Frontend build tool

docs/Structure.md

@@ -0,0 +1,48 @@
+# Repository Structure
+
+## Tech Stack
+
+**Backend:**
+- [Go](https://go.dev/) - Programming language
+- [Gin](https://gin-gonic.com/) - HTTP web framework
+- [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) - OpenAPI code generator
+- [zerolog](https://github.com/rs/zerolog) - Structured logging
+
+**Frontend:**
+- [React](https://react.dev/) - UI framework
+- [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript
+- [Vite](https://vitejs.dev/) - Build tool and dev server
+
+**Deployment:**
+- [Docker](https://www.docker.com/) - Containerization
+
+## Major Components
+
+### api/
+Contains the OpenAPI specification (`openapi.yaml`) and all API-related code. The generated code (`gen.go`) lives here along with the API implementation files (`server.go`, `server_*.go`).
+
+### server/
+Houses the HTTP server setup and embedded frontend. The `web/` subdirectory is populated during the Docker build with the compiled frontend.
+
+### web/
+React application source code built with Vite and TypeScript.
+
+### main.go
+Application entry point that initializes logging and starts the server.
+
+### Makefile
+Contains common development commands including `build`, `run`, `generate`, `fmt`, and `lint`. See the Development Workflow document for details on each command.
+
+## Code Generation Flow
+
+1. `api/openapi.yaml` defines the API specification
+2. `api/server.go` contains `//go:generate go tool oapi-codegen -config ./oapi-codegen.yaml ./openapi.yaml`
+3. Running `go generate ./...` triggers oapi-codegen
+4. `api/gen.go` is generated with types, interfaces, and routing code
+5. `api/server_*.go` files implement the generated interface methods
+
+Adding a new endpoint: define it in `openapi.yaml`, run `make generate`, implement the handler method in a `server_*.go` file. The generated code automatically registers the route with Gin.
+
+## Frontend Embedding
+
+The compiled frontend lives in `server/web/` after the build process. The `//go:embed web` directive in `server/server.go` compiles the entire directory into the Go binary at build time. At runtime, `handleStatic()` serves these files from the embedded filesystem. Requests to paths starting with `/api` are handled by API routes; all other requests are served from the embedded files. If a requested file doesn't exist, `index.html` is served to enable client-side routing for the [Single Page Application (SPA)](https://developer.mozilla.org/en-US/docs/Glossary/SPA).