chatok-jnr/legalaid-backend

1. This repository is a backend-only Spring Boot 3.3 application written in Java 21. It is organized as a modular monolith: one deployable process, with business areas split into separate packages under com.legalaid.

2. The request entrypoint is the REST API layer. Each feature package has a *Controller that accepts HTTP requests, delegates to a *Service, and persists through Spring Data JPA repositories. DTOs are used at the boundary so API shapes stay separate from database entities.

3. Cross-cutting infrastructure lives in config/ and common/. SecurityConfig, JwtConfig, JwtAuthFilter, CorsConfig, and CloudinaryConfig define authentication, CORS, token handling, and external storage wiring. GlobalExceptionHandler and ApiResponse standardize error and success responses across all endpoints.

4. Authentication is centered in auth/. The flow supports Google OAuth token exchange, JWT issuance, token refresh, and logout. JwtAuthFilter protects private routes, while AuthService, GoogleOAuthService, and JwtService handle identity verification and token lifecycle. This is the main security boundary before requests reach domain services.

5. User identity and roles are modeled separately in user/. User, UserRole, and UserService represent platform accounts and role-based state. This package is the base layer that other domains build on, since lawyer, client, and admin behavior all depend on the current authenticated user.

6. Lawyer management is a distinct domain in lawyer/. It contains the core lawyer profile plus specialized sub-entities for availability, courts, languages, locations, practice areas, and verification documents. This package supports onboarding, verification, public profile viewing, and lawyer statistics.

7. Service listings are handled in service/. LegalService and related entities such as ServiceMedia, ServiceFeature, ServiceFaq, and ServiceHighlight represent the marketplace offering a lawyer publishes. The structure suggests a rich listing model with media and metadata rather than a simple title/description record.

8. Contracting is its own bounded context in contract/. Contract, ContractMilestone, status enums, and repositories model the hire flow between client and lawyer. The README’s state-machine behavior is reflected here: contracts move through pending, active, completed, cancelled, and escrow-related states, and milestones are tracked separately from the contract header.

9. Case management lives in case_/. LegalCase is the core case record, with supporting entities for access control, milestones, and tags. This package is important because it defines collaborative legal work: access grants, editor/owner rules, and case-level milestone tracking.

10. Documents are isolated in document/ and are backed by Cloudinary rather than stored locally. DocumentService and CloudinaryService handle upload and metadata persistence, while DocumentRepository stores references in PostgreSQL. This creates a clear split between binary storage in Cloudinary and structured metadata in the database.

11. Payments are modeled in payment/ with both client-side payments and lawyer payouts. Payment, Payout, their status enums, and related DTOs support escrow-like transaction handling, manual verification, release, and withdrawal flows. The backend is the source of truth for payment state; external bKash interaction is represented as submitted transaction IDs plus admin verification.

12. Notifications are a separate domain in notification/. The package includes paginated listing, unread counts, read state updates, and deletion. Architecturally, notifications act as a platform-side side effect of other business actions such as contract updates, payments, or case changes.

13. Persistence is PostgreSQL-centric throughout. Nearly every domain has a repository package using Spring Data JPA, which means the application keeps business rules in services and uses the database as the durable system of record for users, listings, contracts, cases, payments, and documents.

14. The most important runtime flow is: HTTP request → Spring Security/JWT filter → controller → service → repository → PostgreSQL or Cloudinary → DTO response. That flow is consistent across the modules, making the repo a good candidate for an architecture diagram with a shared infrastructure layer and multiple domain boxes beneath it.

15. Testing is lightweight and focused on core service behavior. The repository includes JUnit tests for auth, JWT, and user services, plus a Spring Boot context test. Build and execution are Maven-based via the wrapper scripts, and configuration is driven from application.yaml and test resources.