Fragments API: Securing a Microservice with Cognito
How the Fragments backend uses Express, JWT validation, AWS Cognito, structured routes, and Docker-oriented development practices.
What this project is
Fragments is an Express backend microservice focused on authenticated API development. It starts with a health route and a protected fragments route, then adds AWS Cognito JWT validation, structured routing, logging, Docker-oriented setup, and local developer workflows.
The project is useful because it shows the foundation of a backend service before higher-level product features are added.
Service shape
The server is organized around src/index.js, src/server.js, src/app.js, src/logger.js, src/auth.js, and route modules under src/routes. That keeps bootstrapping, app construction, auth, logging, and route handlers separated.
The public route is a basic health check. The protected route lives under /v1/fragments and requires a valid Cognito ID token. Calling the protected route without a token returns 401 Unauthorized.
Authentication
The project uses Passport, passport-http-bearer, and aws-jwt-verify to validate bearer tokens from AWS Cognito. The important setup values are the Cognito User Pool ID and App Client ID.
This matters because the backend does not simply trust a client-provided user. It verifies the token against Cognito configuration and caches JWKS data so token validation can happen correctly.
Local development
The README documents normal start, dev mode, debug mode, curl verification, and jq usage. Dev mode enables auto-reload and debug logs, while debug mode supports VS Code breakpoints.
That workflow is practical for backend development. You can start with npm start, switch to npm run dev while changing code, and use the debugger when route behavior or auth validation needs deeper inspection.
Docker and environment practices
The repo includes a Dockerfile and docker-compose setup. Environment variables such as port, log level, Cognito pool ID, and Cognito client ID are kept out of source control.
The README also calls out small but important development habits: do not commit .env, keep debug environment files out of git, use specific git add commands, and verify behavior with curl.
Verification flow
A useful backend verification path is:
curl http://localhost:8080
curl -i http://localhost:8080/v1/fragmentsThe first command should return health JSON. The second should return unauthorized without a token. With a valid Cognito ID token in the Authorization header, the protected route should return a successful empty fragments list.
What this demonstrates
Fragments demonstrates backend fundamentals: route structure, environment config, auth middleware, service startup, local debugging, Docker setup, and command-line verification.
Those details are not flashy, but they are the pieces every reliable backend service needs before more complex domain logic is added.