Author: ETOUNDI II Eugène
Email: [email protected]
Location: Lyon, France

Your open platform to explore, access, and discuss free public‑domain and permissively licensed books. 📚

Discover. Read. Review. Share knowledge.

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

1. Vision & Value Proposition
2. Core Features
3. Architecture Overview
4. Service Responsibilities
5. Technology Stack
6. Quick Start (5 Minutes)
7. Running Locally (Detailed)
8. Configuration & Environment
9. Security Model
10. Domain & Use Cases
11. API Strategy
12. Messaging & Events
13. Data & Persistence
14. Testing Approach
15. Scalability & Performance
16. Roadmap
17. Diagrams
18. Folder Map
19. Development Workflow
20. Contributing
21. FAQ
22. Glossary
23. License
24. Acknowledgements

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

Current / Planned (MVP Scope):

Legend: ✅ = Implemented / working • 🚧 = In progress / scaffolded • 🧪 = Experimental • 🔮 = Planned

Future (Post-MVP): reading session, recommendation engine, collection curation, social signals.

Pattern: Microservices + API Gateway + Service Discovery + External Identity Provider + Event Backbone.

Core components:

• 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

Cross-cutting (implemented or planned): validation, OpenAPI docs, RBAC, future observability & resilience.

Backend: Java 21, Spring Boot 3.4.x, Spring Cloud 2024.x, Spring Security, Spring Data JPA, Spring Kafka, OpenFeign, springdoc-openapi, Lombok

Frontend: Angular 19, TypeScript, (future: NgRx / Signals state management)

Infrastructure: Docker Compose, Keycloak, PostgresSQL 17-alpine, Kafka/Zookeeper, Git submodules

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.

Clone with submodules and launch the full stack:

git clone --recurse-submodules https://github.com/eugene-seb/MF-Library.git
cd MF-Library
docker compose up --build

Then visit:

• Eureka: http://localhost:8761
• Gateway (edge API): http://localhost:8765
• Keycloak: http://localhost:8085
• (Add Angular dev separately: see below)

Stop & clean:

docker compose down -v

Backend (example):

cd services/book-service
./mvnw spring-boot:run   # Windows: mvnw.cmd spring-boot:run

Frontend:

cd mflibrary-frontend
npm install
ng serve
# http://localhost:4200

Run tests:

./mvnw test

Update submodules:

git submodule update --init --recursive

Environment is largely scaffolded via docker-compose.yml.

Key runtime variables (compose-managed):

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

• 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

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.

Design Principles:

• Versioned base path: /api/v1/*
• Resource-oriented endpoints
• Consistent error contract (planned):

{
  "timestamp": "2025-01-01T12:00:00Z",
  "path": "/api/v1/books/123",
  "error": "NOT_FOUND",
  "message": "Book not found",
  "requestId": "<trace-id>"
}

• OpenAPI auto-generation (per-service) at /v3/api-docs & /swagger-ui.html
• Future aggregation via API gateway or dedicated API portal

Kafka infrastructure is prepared. Topic candidates:

Legend: 🔮 = Planned • 🚧 = In Progress • ✅ = Active

Future: schema evolution management (Avro/Protobuf + Schema Registry), consumer groups for analytics.

• 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

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.

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

Inline Samples:

TODO: Add a sequence diagram for Review creation lifecycle.

1. Branch: feat/<topic> or fix/<issue>
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)

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.

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.

This project is licensed under the MIT License.

• Open Source frameworks powering the platform
• Community patterns for microservice design & security
• Inspiration: public knowledge & digital library initiatives

Have an idea or found an issue? Open an issue or start a discussion.

"Access to knowledge empowers everyone. Let's build it right." 🌍