From a0a784e0a18e5b65aafaecc9536042bf1a68d527 Mon Sep 17 00:00:00 2001 From: Sean Starkey Date: Tue, 2 Jun 2026 10:00:18 -0600 Subject: [PATCH] Beef up design decisions section --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ab4e067..7612694 100644 --- a/README.md +++ b/README.md @@ -47,13 +47,19 @@ JWT_SECRET=dev-secret-change-me-do-not-use-in-production mvn spring-boot:run ``` ## Design decisions -- Java programming language since Bluestaq is a Java shop -- Maven for building -- Spring Boot as a framework -- H2 for persistence - plan for Postgres -- JPA/Hibernate for SQL -- Flyway for DB schema control -- JWT for auth + +- Java 21 was selected because the challenge is for a Java-oriented backend role and because modern Java records work well for request/response DTOs. +- Spring Boot provides a compact way to build a production-style REST API with validation, dependency injection, security, persistence, and test support without adding much custom framework code. +- Maven is used for dependency management and repeatable local builds because it is widely understood in Java backend environments. +- Spring Security handles authentication boundaries, while a custom JWT filter keeps the API stateless after login. This makes the service easier to run behind a load balancer because requests do not depend on server-side sessions. +- Passwords are stored as BCrypt hashes, never as plaintext. The JWT signing secret is supplied through configuration and should come from a secret manager or environment variable outside local development. +- H2 is used for fast local development and automated tests. PostgreSQL is supported through Docker Compose and a Spring profile because it is a better fit for a production relational datastore. +- JPA/Hibernate keeps the persistence layer concise for this size of application. The schema is still managed explicitly with Flyway so database changes are versioned and repeatable. +- The data model follows the required `User`, `Note`, and `NoteShare` entities, with an added `title` field on notes for a more realistic note-taking API. +- Share records grant read-only access to a specific user. Owners can create, update, delete, and share their notes; shared recipients can only read them. +- UUID primary keys are used so identifiers are opaque and do not expose record counts or ordering. +- The service returns structured error responses for application-level failures so clients can handle validation, authentication, authorization, and conflict cases predictably. +- This implementation favors clarity over extra infrastructure. Features such as refresh tokens, token revocation, audit logging, pagination, rate limiting, and OpenAPI generation would be good production follow-ups. ## Test App A React app located at https://git.seanstarkey.dev/starkey/notes was used to test the API. This app exercises the API and displays REST requests/responses for debugging. It runs in a docker container.