# fuzz-head/book-store architecture

> Architecture diagram of the GitHub repository fuzz-head/book-store, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fuzz-head/book-store
- Repository: https://github.com/fuzz-head/book-store

## Overview

##### Project Type and Purpose
- This is a backend API service written in Go (Golang).
- It exposes HTTP endpoints for user management, authentication (JWT), book resources, and password resets.
- It persists data to a relational database (via the `database` package/`docker-compose.yml`) and includes rate-limiting and role-based middleware.

##### File Structure
Top-Level Folders:
- cmd/server: application entrypoint (`main.go`)
- internal/api: HTTP layer
– handlers (auth, user, book, password reset)
– middleware (auth, rate limiting, roles)
– routes (router setup)
- domain/models: business entities (User, Book, Claims)
- database: DB connection and seeding logic
- pkg/jwtutils & pkg/utils: shared utilities (JWT, hashing)
- docker-compose.yml: brings up the Go service + database
- test files & stress tests: load-test scripts

##### README
- Contains only test/coverage instructions—no architecture details.
- All architectural insight must come from the code layout.

##### Main Components & Their Interactions
a. API Gateway / HTTP Server
- cmd/server → initializes HTTP router (Gorilla Mux or net/http)
- Routes configured in internal/api/routes/router.go
b. Middleware Layer
- AuthMiddleware: validates JWTs via pkg/jwtutils
- RateLimiter: enforces request quotas
- Roles: enforces RBAC
c. Handler Layer
- AuthHandler: login, token issue, password reset
- UserHandler: CRUD on users
- BookHandler: CRUD on books
d. Domain Layer
- domain/models: User, Book, Claims
- business logic lives in handlers calling models
e. Persistence Layer
- database/database.go: DB connection setup
- database/seed.go: initial data seeding
- Uses a SQL database (Postgres, MySQL, etc.) configured in docker-compose
f. Utility Libraries
- pkg/jwtutils/jwt.go: generate & verify JWTs
- pkg/utils/hash.go: password hashing
g. External Components
- Relational Database (Postgres/MySQL)
- (Optional) Email service for password reset

##### Architectural Patterns and Design Principles
- Clean-Layered Architecture:
– HTTP layer → Handlers → Domain models → Database
- Separation of Concerns: clear HTTP, business, persistence layers
- Middleware pipeline for cross-cutting concerns (auth, rate limit)
- Dependency Injection via constructor functions in cmd/server & routes
- Modular utilities under pkg/ for reuse and testing

##### Final Checklist
[ ] All major components (HTTP server, middleware, handlers, domain, DB, utils)
[ ] Notes about technologies (Go modules, Docker, SQL)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Docker Environment"
        direction TB
        Client((Client)):::external
        HTTPServer["HTTP Server"]:::api
        DB[(Relational DB)]:::db
    end

    Client -->|"HTTP/JSON"| HTTPServer
    HTTPServer -->|"initializes router"| Router

    Router["Router"]:::api
    HTTPServer --> Router

    Router --> AuthMiddleware
    AuthMiddleware["Auth Middleware"]:::api
    AuthMiddleware --> RateLimiter

    RateLimiter["Rate Limiting Middleware"]:::api
    RateLimiter --> RolesMiddleware

    RolesMiddleware["Role-Based Access Middleware"]:::api
    RolesMiddleware --> AuthHandler
    RolesMiddleware --> UserHandler
    RolesMiddleware --> BookHandler
    RolesMiddleware --> PasswordResetHandler

    AuthHandler["Auth Handler"]:::api
    AuthHandler -->|"uses JWT utils"| JWTUtil
    AuthHandler -->|"uses Hash utils"| HashUtil

    PasswordResetHandler["Password Reset Handler"]:::api
    PasswordResetHandler -->|"calls Email Service"| EmailService
    PasswordResetHandler -->|"uses Hash utils"| HashUtil

    UserHandler["User Handler"]:::api
    UserHandler --> UserModel
    UserHandler --> DBConnector

    BookHandler["Book Handler"]:::api
    BookHandler --> BookModel
    BookHandler --> DBConnector

    subgraph "Domain Models"
        direction TB
        UserModel["User Model"]:::domain
        BookModel["Book Model"]:::domain
        ClaimsModel["Claims Model"]:::domain
    end

    AuthHandler --> ClaimsModel
    UserHandler --> ClaimsModel

    subgraph "Persistence Layer"
        direction TB
        DBConnector["DB Connection Setup"]:::db
        DBSeed["DB Seeding Logic"]:::db
    end

    DBConnector --> DB
    DBSeed --> DB

    subgraph "Utilities"
        direction TB
        JWTUtil["JWT Utility"]:::util
        HashUtil["Hashing Utility"]:::util
    end

    subgraph "External Services"
        direction TB
        EmailService["Email Service"]:::external
    end

    click HTTPServer "https://github.com/fuzz-head/book-store/blob/main/cmd/server/main.go"
    click Router "https://github.com/fuzz-head/book-store/blob/main/internal/api/routes/router.go"
    click AuthMiddleware "https://github.com/fuzz-head/book-store/blob/main/internal/api/middleware/auth_middleware.go"
    click RateLimiter "https://github.com/fuzz-head/book-store/blob/main/internal/api/middleware/rate_limit.go"
    click RolesMiddleware "https://github.com/fuzz-head/book-store/blob/main/internal/api/middleware/roles.go"
    click AuthHandler "https://github.com/fuzz-head/book-store/blob/main/internal/api/handlers/auth_handler.go"
    click PasswordResetHandler "https://github.com/fuzz-head/book-store/blob/main/internal/api/handlers/password_reset.go"
    click UserHandler "https://github.com/fuzz-head/book-store/blob/main/internal/api/handlers/user_handler.go"
    click BookHandler "https://github.com/fuzz-head/book-store/blob/main/internal/api/handlers/book_handler.go"
    click JWTUtil "https://github.com/fuzz-head/book-store/blob/main/pkg/jwtutils/jwt.go"
    click HashUtil "https://github.com/fuzz-head/book-store/blob/main/pkg/utils/hash.go"
    click UserModel "https://github.com/fuzz-head/book-store/blob/main/domain/models/user.go"
    click BookModel "https://github.com/fuzz-head/book-store/blob/main/domain/models/book.go"
    click ClaimsModel "https://github.com/fuzz-head/book-store/blob/main/domain/models/claims.go"
    click DBConnector "https://github.com/fuzz-head/book-store/blob/main/database/database.go"
    click DBSeed "https://github.com/fuzz-head/book-store/blob/main/database/seed.go"
    click DB "https://github.com/fuzz-head/book-store/blob/main/docker-compose.yml"

    classDef api fill:#D6EAF8,stroke:#1F618D,color:#1B4F72
    classDef domain fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef db fill:#FAD7A0,stroke:#B9770E,color:#874B0F
    classDef util fill:#D7DBDD,stroke:#626567,color:#2C3E50
    classDef external fill:#E8DAEF,stroke:#7D3C98,color:#4A235A
```
