diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..03c09d7 --- /dev/null +++ b/.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/` diff --git a/docs/Getting Started.md b/docs/Getting Started.md new file mode 100644 index 0000000..d07cb50 --- /dev/null +++ b/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 + cd + ``` + +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 diff --git a/docs/Structure.md b/docs/Structure.md new file mode 100644 index 0000000..0bbf5cf --- /dev/null +++ b/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).