# harrishphotos/go_user_auth architecture

> Architecture diagram of the GitHub repository harrishphotos/go_user_auth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harrishphotos/go_user_auth
- Repository: https://github.com/harrishphotos/go_user_auth

## Overview

##### Project Type & Purpose
- Full-stack web service providing user authentication, email verification, and CRUD operations for books and stores.
- Backend: Go (Fiber framework)
- Frontend: React + Vite + TypeScript
- Persistence: PostgreSQL (GORM ORM)
- Messaging: Kafka for asynchronous email/event processing
- Containerization: Docker & Docker Compose

##### Main System Components
A. Client Layer (Frontend)
- React/Vite application served on port (e.g., 3000)
- Pages: Login, Register, Home, Forgot Password, Verify Email
- AuthContext for state, Axios wrapper for API calls

B. API Layer (Go Fiber Backend)
- Entry point: main.go
- Configuration: config/config.go (loads .env)
- Router: routes/routes.go ─ registers auth, book, store sub-routes
- Controllers: controllers/*_controller.go ─ handle HTTP requests, invoke services
- Middleware: middleware/auth_middleware.go & middleware.go ─ PASETO token validation, logging, CORS
- Services:
- email.go ─ constructs and sends emails (via SMTP)
- kafka/producer.go ─ publishes verification/reset messages to Kafka
- kafka/consumer.go ─ subscribed to the same topics when running in consumer mode
- Utilities: password hashing (Argon2id), token generation (PASETO), verification token handling
- Database: database/database.go ─ initializes GORM with PostgreSQL

C. Data Layer
- PostgreSQL container (“postgres”)
- GORM models: models/user.go, book.go, store.go
- Tables for users, tokens, books, stores

D. Messaging Layer
- Kafka broker container (“kafka”)
- Topics: “user-verification”, “password-reset” (or similar)
- Producer in backend publishes events, consumer processes them

E. External Services
- SMTP/Email provider for sending verification and reset emails

F. Deployment Infrastructure
- Docker Compose orchestrates:
- app (Go/Fiber service)
- postgres
- kafka (and implicitly Zookeeper)

##### Relationships & Data Flows
1. User → Browser/React client
- User interacts via UI, triggers API calls
2. React client → HTTP(S) → Go API
- Auth calls: /api/auth/*
- Book calls: /api/book/*
- Store calls: /api/store/*
3. API → PostgreSQL
- GORM ORM reads/writes user, book, store records
4. API → Kafka
- On registration/forgot-password: controllers call kafka.Producer to enqueue messages
5. Kafka → Consumer (could be same app in a consumer role or separate microservice)
- Consumer receives messages, invokes services/email.go to send emails
6. Consumer → SMTP
- SMTP connection to external mail server

##### Architectural Patterns & Design Principles
- Layered (presentation → API router → controllers → services → data)
- MVC-style separation (controllers/models)
- Asynchronous messaging for scalability & reliability (Kafka)
- Token-based stateless authentication (PASETO)
- Containerized, microservice-friendly deployment

- **Client Section**: Browser → React SPA
- **API Section**:
- config → routes → middleware → controllers → services → utils/database
- **Data & Messaging**:
- PostgreSQL ←→ GORM
- Kafka Producer → Kafka Broker → Kafka Consumer → Email Service
- **External**: SMTP server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Compose Boundary
    subgraph "Docker Compose"
        direction TB

        %% Frontend Container
        subgraph "Frontend (frontend/)" 
            direction TB
            React["React SPA"]:::frontend
            MainTSX["main.tsx"]:::frontend
            LoginPage["Login Page"]:::frontend
            RegisterPage["Register Page"]:::frontend
            HomePage["Home Page"]:::frontend
            ForgotPage["Forgot Password Page"]:::frontend
            VerifyPage["Verify Email Page"]:::frontend
            AuthContext["AuthContext"]:::frontend
            AxiosWrapper["Axios Wrapper"]:::frontend
            AuthService["Auth Service"]:::frontend
            TokenUtil["Token Utilities"]:::frontend
        end

        %% Backend Container
        subgraph "Backend (app)"
            direction TB
            MainGo["main.go"]:::backend
            Config["config/config.go"]:::backend
            subgraph "Routing"
                Routes["routes/routes.go"]:::backend
                AuthRoutes["auth_routes.go"]:::backend
                BookRoutes["book_routes.go"]:::backend
                StoreRoutes["store_routes.go"]:::backend
            end
            subgraph "Controllers"
                AuthController["auth_controller.go"]:::backend
                BookController["book_controller.go"]:::backend
                StoreController["store_controller.go"]:::backend
            end
            subgraph "Middleware"
                AuthMW["auth_middleware.go"]:::backend
                GenMW["middleware.go"]:::backend
            end
            subgraph "Services"
                EmailSvc["email.go"]:::backend
                KafkaProd["producer.go"]:::backend
                KafkaCons["consumer.go"]:::backend
                KafkaModels["models.go"]:::backend
            end
            subgraph "Utilities"
                PasswordHash["password.go"]:::backend
                TokenGen["token.go"]:::backend
                VerifyUtil["verification.go"]:::backend
            end
            DBInit["database/database.go"]:::backend
            subgraph "Models"
                UserModel["user.go"]:::backend
                BookModel["book.go"]:::backend
                StoreModel["store.go"]:::backend
            end
        end

        %% Database Container
        Postgres["PostgreSQL"]:::database

        %% Kafka Container
        Kafka["Kafka Broker"]:::broker
    end

    %% External SMTP
    SMTP["SMTP Server"]:::external

    %% Relationships - Synchronous
    React -->|"HTTP/REST"| MainGo
    MainGo --> Config
    MainGo --> Routes
    Routes --> AuthRoutes
    Routes --> BookRoutes
    Routes --> StoreRoutes
    AuthRoutes --> AuthController
    BookRoutes --> BookController
    StoreRoutes --> StoreController
    AuthController --> Services
    BookController --> Services
    StoreController --> Services
    AuthController --> DBInit
    BookController --> DBInit
    StoreController --> DBInit
    DBInit --> Postgres
    AuthController -->|"uses"| PasswordHash
    AuthController --> TokenGen
    AuthController --> VerifyUtil

    %% Asynchronous (dashed)
    AuthController ---->|"produce user-verification"| KafkaProd
    AuthController ---->|"produce password-reset"| KafkaProd
    KafkaProd -->|Kafka protocol| Kafka
    Kafka -->|Kafka protocol| KafkaCons
    KafkaCons --> EmailSvc
    EmailSvc --> SMTP

    %% Click Events Frontend
    click React "https://github.com/harrishphotos/go_user_auth/tree/main/frontend/"
    click MainTSX "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/main.tsx"
    click LoginPage "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/pages/Login.tsx"
    click RegisterPage "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/pages/Register.tsx"
    click HomePage "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/pages/Home.tsx"
    click ForgotPage "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/pages/ForgotPassWord.tsx"
    click VerifyPage "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/pages/VerifyEmailPage.tsx"
    click AuthContext "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/context/AuthContext.tsx"
    click AxiosWrapper "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/api/axiosWrapper.ts"
    click AuthService "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/service/authService.ts"
    click TokenUtil "https://github.com/harrishphotos/go_user_auth/blob/main/frontend/src/utils/tokenUtil.ts"

    %% Click Events Backend
    click MainGo "https://github.com/harrishphotos/go_user_auth/blob/main/main.go"
    click Config "https://github.com/harrishphotos/go_user_auth/blob/main/config/config.go"
    click Routes "https://github.com/harrishphotos/go_user_auth/blob/main/routes/routes.go"
    click AuthRoutes "https://github.com/harrishphotos/go_user_auth/blob/main/routes/auth_routes.go"
    click BookRoutes "https://github.com/harrishphotos/go_user_auth/blob/main/routes/book_routes.go"
    click StoreRoutes "https://github.com/harrishphotos/go_user_auth/blob/main/routes/store_routes.go"
    click AuthController "https://github.com/harrishphotos/go_user_auth/blob/main/controllers/auth_controller.go"
    click BookController "https://github.com/harrishphotos/go_user_auth/blob/main/controllers/book_controller.go"
    click StoreController "https://github.com/harrishphotos/go_user_auth/blob/main/controllers/store_controller.go"
    click AuthMW "https://github.com/harrishphotos/go_user_auth/blob/main/middleware/auth_middleware.go"
    click GenMW "https://github.com/harrishphotos/go_user_auth/blob/main/middleware/middleware.go"
    click EmailSvc "https://github.com/harrishphotos/go_user_auth/blob/main/services/email.go"
    click KafkaProd "https://github.com/harrishphotos/go_user_auth/blob/main/services/kafka/producer.go"
    click KafkaCons "https://github.com/harrishphotos/go_user_auth/blob/main/services/kafka/consumer.go"
    click KafkaModels "https://github.com/harrishphotos/go_user_auth/blob/main/services/kafka/models.go"
    click PasswordHash "https://github.com/harrishphotos/go_user_auth/blob/main/utils/password.go"
    click TokenGen "https://github.com/harrishphotos/go_user_auth/blob/main/utils/token.go"
    click VerifyUtil "https://github.com/harrishphotos/go_user_auth/blob/main/utils/verification.go"
    click DBInit "https://github.com/harrishphotos/go_user_auth/blob/main/database/database.go"
    click UserModel "https://github.com/harrishphotos/go_user_auth/blob/main/models/user.go"
    click BookModel "https://github.com/harrishphotos/go_user_auth/blob/main/models/book.go"
    click StoreModel "https://github.com/harrishphotos/go_user_auth/blob/main/models/store.go"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404;
    classDef broker fill:#ffeeba,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
