📚 LibreCore

A modular Library Management REST API built with Go, following clean architecture principles and a strict separation of domain, service, and infrastructure layers.

---

Tech Stack

• Go 1.26
• Gin (HTTP framework)
• PostgreSQL 16
• Redis
• Elasticsearch 8
• JWT (RS256)
• Swagger / OpenAPI 3
• Docker + Docker Compose
• GitHub Actions (CI)

---

Architecture

HTTP (Gin Router)
   → Middleware (auth, logging, rate limit, recovery)
      → Handler layer (request/response)
         → Service layer (business logic)
            → Repository layer (PostgreSQL)
               → External systems (Redis, Elasticsearch)

• handler/ → HTTP transport layer only
• service/ → business rules
• repository/ → DB access (Postgres)
• search/ → Elasticsearch integration
• middleware/ → cross-cutting concerns
• domain/ → core models & domain logic

---

Project Structure

cmd/
  api/            REST API server (routers, DI, bootstrap)
  migrate/        DB migration CLI
  seed/           database seeding tool

internal/
  domain/         business models + domain rules
  handler/        HTTP controllers (backoffice + portal)
  service/        business logic layer
  repository/     database layer
  middleware/     auth, logging, security, rate limit
  search/         Elasticsearch client + queries

pkg/
  cache/          Redis abstraction
  database/       Postgres helpers
  errors/         typed error system
  i18n/           localization
  logger/         structured logging
  mailer/         email service
  otp/            OTP generation/validation
  response/       HTTP response helpers
  session/        session utilities
  validator/      input validation

configs/          configuration (db, redis, env)
migrations/       SQL migrations
docs/             Swagger + architecture docs
tests/            integration tests + mocks

---

API Overview

Backoffice (Admin APIs)

Auth

POST /api/v1/backoffice/auth/login
POST /api/v1/backoffice/auth/refresh
POST /api/v1/backoffice/auth/forgot-password
POST /api/v1/backoffice/auth/reset-password
POST /api/v1/backoffice/auth/logout

Books

GET    /api/v1/backoffice/books
GET    /api/v1/backoffice/books/:id
POST   /api/v1/backoffice/books
PUT    /api/v1/backoffice/books/:id
DELETE /api/v1/backoffice/books/:id
POST   /api/v1/backoffice/books/:id/copies/add
POST   /api/v1/backoffice/books/:id/copies/remove

Customers

GET    /api/v1/backoffice/customers
GET    /api/v1/backoffice/customers/:id
POST   /api/v1/backoffice/customers
PUT    /api/v1/backoffice/customers/:id
DELETE /api/v1/backoffice/customers/:id

Employees

GET    /api/v1/backoffice/employees
GET    /api/v1/backoffice/employees/:id
POST   /api/v1/backoffice/employees
PUT    /api/v1/backoffice/employees/:id
DELETE /api/v1/backoffice/employees/:id

Borrows

GET  /api/v1/backoffice/borrows
POST /api/v1/backoffice/borrows
PUT  /api/v1/backoffice/borrows/:id/return

GET  /api/v1/backoffice/borrows/customers/:id

Search

GET /api/v1/backoffice/search/books
GET /api/v1/backoffice/search/books/suggest

Reports

GET /api/v1/backoffice/reports/borrows/trends
GET /api/v1/backoffice/reports/borrows/overdue
GET /api/v1/backoffice/reports/books/top
GET /api/v1/backoffice/reports/books/low-availability
GET /api/v1/backoffice/reports/customers/top
GET /api/v1/backoffice/reports/genres/popularity
GET /api/v1/backoffice/reports/summary/monthly

---

Portal (Customer APIs)

Auth

POST /api/v1/portal/auth/signup
POST /api/v1/portal/auth/login
POST /api/v1/portal/auth/refresh
POST /api/v1/portal/auth/logout
POST /api/v1/portal/auth/forgot-password
POST /api/v1/portal/auth/reset-password
GET  /api/v1/portal/auth/google
GET  /api/v1/portal/auth/google/callback

Books

GET /api/v1/portal/books
GET /api/v1/portal/books/:id
GET /api/v1/portal/books/search
GET /api/v1/portal/books/suggest
GET /api/v1/portal/books/:id/recommendations

Customer profile

GET /api/v1/portal/me
PUT /api/v1/portal/me
GET /api/v1/portal/me/borrows
GET /api/v1/portal/me/recommendations

---

Public Search

GET /api/v1/search/books
GET /api/v1/search/books/suggest

---

Features

• Book inventory management (copies, availability tracking)
• Customer & employee management system
• Role-based access control (backoffice vs portal)
• Borrow/return lifecycle management
• Full-text search with Elasticsearch
• Recommendation engine (item + profile based)
• Reporting system (borrows, trends, analytics)
• JWT authentication with refresh tokens
• Google OAuth login support
• Pagination + filtering across all list endpoints

---

Build & Run

make docker-up
make migrate
make run-api

---

Makefile (core commands)

make run-api
make build
make test
make lint
make migrate
make seed
make docker-up

---

Notes on Design

• Clean separation of backoffice and portal APIs
• Domain-driven internal structure
• Elasticsearch used as a derived read model
• Services are the only layer containing business logic
• Handlers are strictly transport adapters

---

License

MIT

---