shaig-mahmudov/rivet-api

1. What this repo is

- Rivet is a single Spring Boot backend service for engineering workflow management.

- The runtime is a classic layered Java backend: HTTP controllers at the edge, service layer for business rules, JPA repositories for persistence, and Flyway-managed relational schemas underneath.

2. Top-level request flow

- Requests enter Spring MVC controllers under auth, user, project, task, and ai.

- Most endpoints flow through service interfaces/implementations, then into repositories backed by JPA entities.

- Cross-cutting concerns like auth, validation, and exception mapping are centralized rather than duplicated in each module.

3. Security boundary

- Authentication is stateless JWT-based.

- JwtAuthenticationFilter and SecurityConfig enforce protected routes and populate the current user context.

- Passwords are hashed with BCrypt, access tokens are validated by JWT service logic, and logout/refresh flows depend on a token blacklist plus refresh-token persistence.

- Admin-only behavior is enforced at the API/service boundary, especially for hard delete and user-management actions.

4. Auth subsystem

- The auth module handles register, login, refresh, logout, and bootstrap-admin flows.

- Refresh tokens are first-class data: they are issued, rotated, revoked, hashed, and stored via RefreshToken plus RefreshTokenRepository.

- Blacklisted access tokens can be stored in-memory or in Redis, which is an architectural switch controlled by configuration.

5. Core domain modules

- project, task, and user are the main business domains.

- Each follows the same internal pattern: controller → DTOs → service abstraction/implementation → repository → entity/mapper.

- This makes the architecture diagram naturally split into three symmetric business areas, with task being the most complex one.

6. Task is the central aggregate

- The task module contains the richest business logic: status transitions, priority changes, partial updates, soft/hard delete, restore, filtering, and project/user assignment.

- TaskStatusTransitionPolicy and the transition service encode workflow rules, including allowed transitions and reason-required states.

- The task entity also anchors related features: activities, comments, dependencies, and acceptance criteria.

7. Task subdomains

- Activity timeline: task lifecycle events are recorded as read-only TaskActivity entries and surfaced through timeline endpoints.

- Comments: nested comment endpoints support discussion and blocker notes tied to tasks.

- Dependencies: tasks can depend on other tasks, with guards against self-dependency, duplicates, cross-project links, and cycles.

- Acceptance criteria: manual criteria can be created in bulk, completed/reopened, and are enforced before a task can move to DONE.

8. AI integration boundary

- The AI module is isolated from the core persistence workflow.

- AiSuggestionController and AiAcceptanceCriteriaService generate draft acceptance-criteria suggestions for a task but do not persist them.

- AiProvider abstracts the external model provider; a disabled provider exists by default, and a Gemini implementation is available when configured.

- This is a deliberate boundary: AI assists users, but saved criteria still flow through the normal task/criteria APIs.

9. Persistence model

- JPA entities live alongside each domain and map to relational tables created by Flyway.

- BaseEntity suggests common audit fields and shared persistence behavior.

- The repository layer is thin and domain-specific: project/task/user plus child tables for comments, activities, dependencies, criteria, and refresh tokens.

10. Database and migration strategy

- The repo supports MySQL for development, PostgreSQL for production, and H2 for tests.

- Flyway migrations are duplicated per database family under db/migration/mysql and db/migration/postgresql.

- Schema validation tests verify that the SQL migrations and Hibernate mappings stay aligned across both dialects.

11. Configuration and environment boundaries

- Runtime behavior is environment-driven through application.properties, application-dev.properties, and application-prod.properties.

- Important deployment toggles include DB URL/credentials, JWT secrets, refresh-token retention, Redis settings, and AI provider credentials.

- The Docker Compose setup starts the API with MySQL and Redis, matching the production-style token-blacklist architecture more closely than the default in-memory mode.

12. Error handling and API contract

- Domain-specific exceptions are centralized in common/exception, with GlobalExceptionHandler converting them into structured ErrorResponse payloads.

- Validation errors are surfaced at the field level through Bean Validation and the exception layer.

- This keeps controllers thin and ensures consistent failure semantics across auth, project, task, and user operations.

13. Testing and delivery

- The test suite covers controller and service behavior for auth, project, task, and user modules.

- Dedicated migration-validation tests check the SQL schema for both MySQL and PostgreSQL.

- CI is GitHub Actions–based, and the repo includes both a Dockerfile and compose file for containerized execution.

14. How to draw the architecture

- A good diagram would show: clients → Spring MVC controllers → domain services → repositories → relational DB.

- Add a separate security lane for JWT filter, refresh-token service, and blacklist store.

- Add a side integration box for AI provider access, connected only through the AI suggestion service.

- Show Flyway as the schema provisioning path, and Redis as an optional infrastructure dependency used by token blacklisting.