Beef up design decisions section

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.