diff --git a/README.md b/README.md index a3da5d8..ff155b2 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,481 @@ # MF Library -**Author:** ETOUNDI II Eugene +**Author:** ETOUNDI II Eugรจne **Email:** etoundisebastien@gmail.com **Location:** Lyon, France -*** +> Your open platform to explore, access, and discuss free publicโ€‘domain and permissively licensed +> books. ๐Ÿ“š +> +> Discover. Read. Review. Share knowledge. + +--- + +## ๐Ÿ”ฅ Why MF Library? + +MF Library aims to deliver a modern, scalable and secure platform where users can: + +- ๐Ÿ” Search and browse a curated catalog of free books +- ๐Ÿ“– View rich book metadata and (future) embedded readers +- โญ Rate and review titles to guide others +- ๐Ÿ›ก๏ธ Benefit from a secure, token-based architecture +- ๐Ÿš€ Experience a cloud-ready microservices foundation + +--- + +## ๐Ÿงญ Table of Contents + +1. [Vision & Value Proposition](#-vision--value-proposition) +2. [Core Features](#-core-features) +3. [Architecture Overview](#-architecture-overview) +4. [Service Responsibilities](#-service-responsibilities) +5. [Technology Stack](#-technology-stack) +6. [Quick Start (5 Minutes)](#-quick-start-5-minutes) +7. [Running Locally (Detailed)](#-running-locally-detailed) +8. [Configuration & Environment](#-configuration--environment) +9. [Security Model](#-security-model) +10. [Domain & Use Cases](#-domain--use-cases) +11. [API Strategy](#-api-strategy) +12. [Messaging & Events](#-messaging--events) +13. [Data & Persistence](#-data--persistence) +14. [Testing Approach](#-testing-approach) +15. [Scalability & Performance](#-scalability--performance) +16. [Roadmap](#-roadmap) +17. [Diagrams](#-diagrams) +18. [Folder Map](#-folder-map) +19. [Development Workflow](#-development-workflow) +20. [Contributing](#-contributing) +21. [FAQ](#-faq) +22. [Glossary](#-glossary) +23. [License](#-license) +24. [Acknowledgements](#-acknowledgements) -The issues are tracked and available [**here**](https://github.com/users/eugene-seb/projects/1) +--- -Cloning the main repo with submodules +## ๐ŸŽฏ Vision & Value Proposition -- `git clone --recurse-submodules https://github.com/eugene-seb/MF-Library.git` +MF Library is engineered to be an extensible knowledge platform built on a robust microservice +foundation. Its design emphasizes: -*** +- Separation of domains (users, books, reviews) +- Cloud and container readiness from day one +- Strong security and future observability +- Event-driven evolution with Kafka +- Developer friendliness and clarity -## Project description +--- -## Context +## โœ… Core Features -The **MF Library** (**M**y **F**ree **Library**) was born from the need to explore and apply * -*Spring Cloud** in a -real-world microservices architecture. The objective was to gain hands-on experience in **Spring -Boot, Spring Cloud, and -microservices deployment**, while designing a **scalable and maintainable application**. By -implementing industryโ€™s best -practices, this project serve as a practical learning experience in **distributed systems, API -management, and cloud -infrastructure**. +Current / Planned (MVP Scope): -## Objective +| Feature | Status | Notes | +|-----------------------------------------|:------:|---------------------------------------------------------| +| User authentication & accounts | ๐Ÿšง | Keycloak realm import available; UI integration pending | +| Browse book catalog | ๐Ÿšง | Book service scaffold ready | +| Book search (title/author) | ๐Ÿšง | Repository queries to implement | +| View book details + aggregated rating | ๐Ÿšง | Rating aggregation design TBD | +| Submit & manage reviews | ๐Ÿšง | Review service base in place | +| API gateway routing & service discovery | โœ… | Eureka + Gateway operational | +| Secured endpoints (JWT) | ๐Ÿšง | Resource server dependencies present | +| OpenAPI docs per service | ๐Ÿšง | springdoc configured (expand aggregation) | +| Event publication (Kafka) | ๐Ÿšง | Topics & consumers definition pending | +| Responsive Angular SPA shell | โœ… | Frontend scaffold running | -The goal of **MF Library** is to create an **online platform** where users can access a vast -collection of **free public -domain books**. The platform will allow users to: +Legend: โœ… = Implemented / working โ€ข ๐Ÿšง = In progress / scaffolded โ€ข ๐Ÿงช = Experimental โ€ข ๐Ÿ”ฎ = Planned -- **Search, browse, and read books** available in the database. -- **Create an account** to personalize their experience. -- **Rate and review books** to provide community-driven recommendations. +Future (Post-MVP): reading session, recommendation engine, collection curation, social signals. -This system should be **scalable, resilient, and easy to extend**, ensuring a seamless experience -for users. +--- -## Technical Description +## ๐Ÿ—๏ธ Architecture Overview -### System Architecture +Pattern: Microservices + API Gateway + Service Discovery + External Identity Provider + Event +Backbone. -MF Library follows a **microservices architecture** using **Spring Cloud**, allowing independent -services to communicate -efficiently while ensuring modularity. +Core components: -#### **1. User Service** +- Gateway โ†’ single ingress, policy, routing +- Eureka โ†’ discovery registry +- Keycloak โ†’ authentication / OIDC provider +- Domain services โ†’ user, book, review verticals +- Kafka โ†’ asynchronous decoupling & future analytics pipeline +- PostgresSQL โ†’ relational persistence (per bounded context) +- Angular SPA โ†’ user-facing interface -- Handles authentication and user profile management. -- Manages roles and permissions for accessing different features. +Cross-cutting (implemented or planned): validation, OpenAPI docs, RBAC, future observability & +resilience. -#### **2. Book Service** +
Planned Enhancements + +
-- Stores and retrieves book information (title, author, genre, etc.). -- Supports book categorization and metadata management. +--- -#### **3. Review Service** +## ๐Ÿงฉ Service Responsibilities -- Allows users to leave reviews and ratings for books. -- Connects user feedback to books for community engagement. +| Service | Port | Responsibility | Tech Highlights | +|-------------------|---------------------|-----------------------------------------|------------------------------------| +| Registry (Eureka) | 8761 | Dynamic service discovery | Spring Cloud Netflix Eureka Server | +| API Gateway | 8765 | Edge routing, security delegation, CORS | Spring Cloud Gateway | +| User Service | 8081 | User profiles & identity linkage | Spring Boot, Security, JPA | +| Book Service | 8082 | Catalog, metadata, classification | Spring Boot, JPA, OpenAPI | +| Review Service | 8083 | Ratings & textual reviews | JPA, Kafka-ready, Feign (future) | +| Keycloak | 8085 | OIDC provider & token service | Keycloak 24.x | +| Kafka + Zookeeper | 29092 / 9092 / 2181 | Event messaging backbone | Confluent images | +| PostgreSQL | 5432 | Relational persistence | Separate schemas (strategy) | +| Frontend | 4200 (dev) | SPA UX | Angular 19 | -#### **4. API Gateway** +--- -- A central entry point for routing requests to appropriate microservices. -- Manages authentication, rate-limiting, and request forwarding. +## ๐Ÿ› ๏ธ Technology Stack -#### **5. Service Discovery & Configuration** *(Spring Cloud Eureka & Config Server)* +**Backend:** Java 21, Spring Boot 3.4.x, Spring Cloud 2024.x, Spring Security, Spring Data JPA, +Spring Kafka, OpenFeign, springdoc-openapi, Lombok -- Helps in dynamic service registration and automatic discovery. -- Manages centralized configuration for microservices. +**Frontend:** Angular 19, TypeScript, (future: NgRx / Signals state management) -### **Technologies & Tools** +**Infrastructure:** Docker Compose, Keycloak, PostgresSQL 17-alpine, Kafka/Zookeeper, Git submodules -- **Database** - - **PostgreSQL** is the primary database engine chosen for its robustness and compatibility with - Spring Boot. - - Each microservice will have **its own database instance**. +**Testing:** Spring Boot Test, H2, Kafka Test, Security Test, Reactor Test, (planned: +Test containers, Contract Tests) +**Planned Observability:** Micrometer + Prometheus, Grafana, OpenTelemetry, structured logging +pipeline. -- Docker & Kubernetes -- Cloud Hosting (AWS or Local Kubernetes Cluster) -- Spring Cloud Config & Eureka Server, Kafka -- CI/CD Pipeline (GitHub Actions) +--- +## โšก Quick Start (5 Minutes) -- **Security & API Management** - - Spring Security + JWT/OAuth2 - - Rate-limiting in API Gateway - - Role-Based Access Control (RBAC) +Clone with submodules and launch the full stack: -## UML Diagrams +```bash +git clone --recurse-submodules https://github.com/eugene-seb/MF-Library.git +cd MF-Library +docker compose up --build +``` -- **Deployment Diagram** +Then visit: -![](doc/images/Deployment-Diagram.png "Deployement diagram") +- Eureka: http://localhost:8761 +- Gateway (edge API): http://localhost:8765 +- Keycloak: http://localhost:8085 +- (Add Angular dev separately: see below) -- **Flow of a User Request** +Stop & clean: -![Flow Diagram](doc/images/Flow-user-request.png "Flow user request") +```bash +docker compose down -v +``` -- **Domain Class Diagram** +--- -![Domain Diagram](doc/images/Domain-class-diagram.png "Domain class diagram") +## ๐Ÿงช Running Locally (Detailed) -## References +Backend (example): -- [Best Practices in Spring Boot Project Structure](https://medium.com/learnwithnk/best-practices-in-spring-boot-project-structure-layers-of-microservice-versioning-in-api-cadf62bd3459) | - by Nadeem Khan (NK) | LearnWithNK | Medium +```bash +cd services/book-service +./mvnw spring-boot:run # Windows: mvnw.cmd spring-boot:run +``` + +Frontend: + +```bash +cd mflibrary-frontend +npm install +ng serve +# http://localhost:4200 +``` + +Run tests: + +```bash +./mvnw test +``` + +Update submodules: + +```bash +git submodule update --init --recursive +``` + +--- + +## โš™๏ธ Configuration & Environment + +Environment is largely scaffolded via `docker-compose.yml`. + +Key runtime variables (compose-managed): + +| Component | Key Variables (non-exhaustive) | +|-----------------|-----------------------------------------------------------------------------------------------| +| Zookeeper | `ZOOKEEPER_CLIENT_PORT`, `ZOOKEEPER_TICK_TIME` | +| Kafka | `KAFKA_BROKER_ID`, `KAFKA_ZOOKEEPER_CONNECT`, `KAFKA_LISTENERS`, `KAFKA_ADVERTISED_LISTENERS` | +| Keycloak | `KEYCLOAK_ADMIN`, `KEYCLOAK_ADMIN_PASSWORD` | +| Postgres | `POSTGRES_USER`, `POSTGRES_PASSWORD` | +| Spring Services | `SPRING_PROFILES_ACTIVE=docker` | + +Suggested future `.env` (example placeholder): + +``` +POSTGRES_USER=postgres +POSTGRES_PASSWORD=postgres +KEYCLOAK_ADMIN=admin +KEYCLOAK_ADMIN_PASSWORD=admin +SPRING_PROFILES_ACTIVE=local +``` + +Keycloak realm import JSON files (mounted): + +- `.infra/keycloak/app-mflibrary-realm-export.json` +- `.infra/keycloak/master-realm-export.json` + +--- + +## ๐Ÿ” Security Model + +- Identity via Keycloak (OIDC): Users authenticate in the browser โ†’ tokens passed to backend +- Resource services validate JWT (Spring Security + OAuth2 Resource Server) +- Planned roles: `ROLE_USER`, `ROLE_ADMIN` +- Future: Fine-grained scopes (e.g. `books.read`, `reviews.write`), audit events, rate limiting + +Auth Flow (simplified): +User โ†’ Browser SPA โ†’ Keycloak Login โ†’ Receives ID + Access Token โ†’ Calls Gateway โ†’ Gateway forwards +with token โ†’ Resource service validates & authorizes + +--- + +## ๐Ÿ“˜ Domain & Use Cases + +Actors: Visitor, Registered User, Administrator. + +Primary Flows: + +1. Browse Catalog โ†’ list books with pagination & filters +2. Book Detail โ†’ fetch metadata + aggregated rating +3. Register/Login โ†’ delegated to Keycloak (redirect flow) +4. Submit Review โ†’ authenticated user posts rating/comment +5. Moderate Reviews (admin) โ†’ approve/remove + +Planned Event Flow (future): +ReviewCreated โ†’ Kafka topic โ†’ Aggregator updates rating snapshot. + +--- + +## ๐Ÿงฉ API Strategy + +Design Principles: + +- Versioned base path: `/api/v1/*` +- Resource-oriented endpoints +- Consistent error contract (planned): + +```json +{ + "timestamp": "2025-01-01T12:00:00Z", + "path": "/api/v1/books/123", + "error": "NOT_FOUND", + "message": "Book not found", + "requestId": "" +} +``` + +- OpenAPI auto-generation (per-service) at `/v3/api-docs` & `/swagger-ui.html` +- Future aggregation via API gateway or dedicated API portal + +--- + +## ๐Ÿ“ก Messaging & Events + +Kafka infrastructure is prepared. Topic candidates: + +| Topic | Purpose | Status | +|-------------------|-----------------------------------------------|:------:| +| `reviews.created` | Trigger rating aggregation / analytics | ๐Ÿ”ฎ | +| `reviews.updated` | Recompute rating delta | ๐Ÿ”ฎ | +| `books.activity` | Track popular titles / future recommendations | ๐Ÿ”ฎ | + +Legend: ๐Ÿ”ฎ = Planned โ€ข ๐Ÿšง = In Progress โ€ข โœ… = Active + +Future: schema evolution management (Avro/Protobuf + Schema Registry), consumer groups for +analytics. + +--- + +## ๐Ÿ—„๏ธ Data & Persistence + +- PostgresSQL as primary store (one DB per service or schema-based isolation strategy) +- JPA/Hibernate with migration tooling (Liquibase/Flyway planned) +- H2 for test isolation +- Future: caching layer (Redis) for book metadata & aggregated ratings + +--- + +## ๐Ÿงช Testing Approach + +| Layer | Current | Planned | +|-------------|-----------------------------------------|-----------------------------------------| +| Unit | Spring Boot Test | More domain-only tests | +| Integration | H2 + MockMVC + embedded Kafka test libs | Test-containers-based infra replication | +| Contract | โ€” | Spring Cloud Contract | +| E2E | โ€” | Postman/Cypress pipeline | +| Performance | โ€” | Gatling / k6 benchmarks | + +--- + +## ๐Ÿš€ Scalability & Performance + +Prepared Strategies: + +- Stateless services โ†’ horizontal scaling +- Independent deployability โ†’ reduced blast radius +- Event-driven async operations (Kafka) to decouple heavy workflows +- Gateway filtering for rate limiting (planned) +- Observability for capacity planning (metrics/tracing planned) + +Future: CDN for static assets, query optimization, caching, read replicas. + +--- + +## ๐Ÿ—บ๏ธ Roadmap + +Short-Term: + +- Book search endpoints +- Review submission + retrieval +- OAuth2 flow integration on frontend +- Standard error model & gateway filters + +Mid-Term: + +- Kafka event flows (rating aggregation) +- Observability stack & tracing +- Admin web module +- Config server adoption + +Long-Term: + +- Recommendation engine +- Ingestion pipeline (EPUB/PDF parsing) +- Multi-language support +- Kubernetes deployment & autoscaling + +--- + +## ๐Ÿ–ผ๏ธ Diagrams + +| Diagram | File | +|----------------------------------------|---------------------------------------| +| Deployment | `doc/images/Deployment-Diagram.png` | +| User Request Flow | `doc/images/Flow-user-request.png` | +| Domain Model | `doc/images/Domain-class-diagram.png` | +| Components | `doc/images/Components-diagram.png` | +| Sequence (Review Submit - Placeholder) | (Add) | +| API Interaction Map (Placeholder) | (Add) | + +Inline Samples: +![Deployment](doc/images/Deployment-Diagram.png) +![User Flow](doc/images/Flow-user-request.png) +![Domain Model](doc/images/Domain-class-diagram.png) +![Components](doc/images/Components-diagram.png) + +> TODO: Add a sequence diagram for Review creation lifecycle. + +--- + +## ๐Ÿ“‚ Folder Map + +| Path | Purpose | +|-----------------------|----------------------------------------| +| `docker-compose.yml` | Orchestrates infra + services | +| `services/` | Active microservice implementations | +| `submodules/` | Mirrored submodule repositories | +| `mflibrary-frontend/` | Angular SPA project | +| `doc/images/` | Architecture & UML diagrams | +| `.infra/keycloak/` | Realm import JSON (mounted in compose) | +| `README.md` | This documentation | +| `TODO.md` | Internal task notes | + +--- + +## ๐Ÿ” Development Workflow + +1. Branch: `feat/` or `fix/` +2. Implement + add/update tests +3. Validate locally (`./mvnw test` + manual service run) +4. Commit atomic changes; reference issues when applicable +5. Open PR for review (future CI automation) +6. Merge โ†’ prepare container publish (future pipeline) + +--- + +## ๐Ÿค Contributing + +External contribution guidelines will be formalized. For now: + +- Use conventional commit style if possible (e.g. `feat: add search endpoint`) +- Keep PRs focused & small +- Document architectural-impacting changes +- Prefer adding tests with new features + +Planned docs: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`. + +--- + +## โ“ FAQ + +**Q: Can I add proprietary books?** +A: Only if licensing permits. Default positioning is public-domain / permissively licensed content. + +**Q: Where do I configure Keycloak realms?** +A: See `.infra/keycloak/*.json` imported at container startup. + +**Q: How do I reset Postgres data?** +A: `docker compose down -v` removes volumes (all data lost). Use with caution. + +**Q: Does the gateway aggregate OpenAPI yet?** +A: Not yetโ€”planned in roadmap. + +**Q: Is horizontal scaling supported?** +A: Architecture enables it; orchestration (Kubernetes) is a future milestone. + +--- + +## ๐Ÿ“˜ Glossary + +| Term | Meaning | +|-----------------|------------------------------------------------------------| +| Bounded Context | Independently modeled domain service (DDD principle) | +| Resource Server | OAuth2-protected API validating JWT tokens | +| Gateway | Edge service handling routing and cross-cutting concerns | +| Realm | Keycloak logical tenant boundary for users, roles, clients | +| Event | Asynchronous message published to Kafka topic | + +--- + +## ๐Ÿ“„ License + +License not yet finalized. Recommended candidates: MIT or Apache-2.0. +(Planned: add `LICENSE` file and badge.) + +--- + +## ๐Ÿ™ Acknowledgements + +- Open Source frameworks powering the platform +- Community patterns for microservice design & security +- Inspiration: public knowledge & digital library initiatives + +--- + +## ๐Ÿ“ฌ Feedback + +Have an idea or found an issue? Open an issue or start a discussion. + +> "Access to knowledge empowers everyone. Let's build it right." ๐ŸŒ diff --git a/submodules/book-service b/submodules/book-service index 4bb1336..851f609 160000 --- a/submodules/book-service +++ b/submodules/book-service @@ -1 +1 @@ -Subproject commit 4bb1336a77b5d6b47ba7c9e513b778fa658407b2 +Subproject commit 851f609cb9779146a5e5147de8f7d4b4e4d6a142 diff --git a/submodules/review-service b/submodules/review-service index 72c82d9..ababb8b 160000 --- a/submodules/review-service +++ b/submodules/review-service @@ -1 +1 @@ -Subproject commit 72c82d94d65819fdf73500c50350101b3b0724eb +Subproject commit ababb8bd6625d97df18c6a16a3cc40bcaae440d7 diff --git a/submodules/user-service b/submodules/user-service index 507007b..b4651e6 160000 --- a/submodules/user-service +++ b/submodules/user-service @@ -1 +1 @@ -Subproject commit 507007bb15bf23d2acf9ff5df4bfbee4475af218 +Subproject commit b4651e65a33569bf9f260f8f6119e9e5cd74d508