diff --git a/README.md b/README.md
index b991429..1b9e5da 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,32 @@
 # Go HTTP server
 
-A simple Go HTTP server boilerplate with Echo, structured logging, and Docker support.
+A simple Go HTTP server boilerplate with Echo, structured logging, and Docker support. Includes graceful shutdown on `SIGINT`/`SIGTERM` via `errgroup`.
+
+## Project layout
+
+    cmd/app/                     entrypoint, wiring, graceful shutdown
+    cmd/app/handler/             HTTP handlers and route registration
+    internal/config/             env-based configuration
+    internal/domain/             your business logic goes here
+    internal/infrastructure/os/  signal handling
+    pkg/logger/                  Zap logger setup
+
+## Endpoints
+
+| Method | Path      | Description               |
+|--------|-----------|---------------------------|
+| GET    | `/health` | Liveness check (`200 OK`) |
+
+## Adding an endpoint
+
+Register routes in a `setup…Routes` method and call it from `handler.New`
+(see `cmd/app/handler/health.go`):
+
+```go
+func (h *Handler) setupFooRoutes(e *echo.Echo) {
+    e.GET("/foo", h.getFoo)
+}
+```
 
 ## Prerequisites