Project: Pulse API

GitHub repository: pulse-api

Pulse API is a small, containerized Next.js service that exposes basic API routes, records request notes on a persistent Docker volume, and provides a health endpoint for Docker Compose.

Project requirements

Repotree

├── app
│   ├── api
│   │   ├── health
│   │   │   └── route.ts
│   │   └── notes
│   │       └── route.ts
│   ├── lib
│   │   └── notes.ts
│   ├── layout.tsx
│   └── page.tsx
├── .dockerignore
├── .env.example
├── .gitignore
├── compose.yaml
├── Dockerfile
├── next-env.d.ts
├── next.config.ts
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

Goal

Deliver a lightweight web API that can be started locally with Docker Compose and used as a foundation for future services.

Functional requirements

• Provide GET /api/health to report application health.
• Provide GET /api/notes to retrieve stored notes.
• Provide POST /api/notes to create a note with a message field.
• Persist notes in a mounted Docker volume so they survive container recreation.

Technical requirements

• Use Next.js route handlers and Node.js.
• Use a multi-stage Docker build to keep the runtime image small.
• Use Docker Compose for local execution.
• Configure the service through environment variables.
• Add a container health check that calls the health endpoint.
• Run the application as a non-root user in the final image.

API

Method	Endpoint	Purpose
GET	/api/health	Health status, service name, and timestamp
GET	/api/notes	List persisted notes
POST	/api/notes	Create a note: { "message": "Hello" }

Run with Docker Compose

1. Optionally copy the environment file: Copy-Item .env.example .env
2. Start the API: docker compose up --build
3. Visit http://localhost:3000/api/health.

The Compose service mounts the named pulse-data volume at /app/data. The API writes its JSON data there, so notes remain after docker compose down and a subsequent up.

Environment variables

Variable	Default	Description
PORT	3000	Port listened to by the Next.js server
SERVICE_NAME	pulse-api	Name returned by the health endpoint
DATA_DIR	/app/data in Docker	Directory used for persistent note storage

Local development

npm install
npm run dev

For local development, set DATA_DIR=./data in .env.local if you want notes saved inside the project folder.

Verification

curl http://localhost:3000/api/health
curl -Method Post http://localhost:3000/api/notes -ContentType 'application/json' -Body '{"message":"Container is running"}'
curl http://localhost:3000/api/notes