# bassemhalim/memedb architecture

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

- Interactive diagram: https://gitdiagram.com/bassemhalim/memedb
- Repository: https://github.com/bassemhalim/memedb

## Overview

##### Project Type and Purpose
- This is “MemeHub,” a full‐stack, microservice‐based meme‐sharing platform.
- Frontend: Next.js (React) handles UI, SSR, i18n (ar/en), meme generation, upload/search pages.
- Backend: Go microservices exposed via REST (Gateway) and gRPC (MemeService).
- Data store: PostgreSQL for metadata; local file system for image blobs.
- Auxiliary services: rate‐limiter, queue, moderator for content filtering.

##### High‐Level Architectural Components
a. Client (Next.js)
- Docker container with the `client/` directory.
- Routes: `/generator`, `/meme/[id]`, `/search`, `/admin`.
- UI components: MemeGenerator, UploadMemeForm, MemeCard, etc.
- Localization module (i18n).

b. API Gateway (Go)
- Docker container built from `services/gateway.Dockerfile`.
- Exposes REST endpoints (`/api/memes`, `/api/search`, `/api/admin`).
- Internal modules:
- auth (JWT/session, `internal/auth`)
- rate‐limiter (IP + token bucket under `services/rate-limiter`)
- validation middleware (`internal/middleware`)
- fileserver (`internal/fileserver`) serves static images from shared volume
- gRPC client (`internal/server/grpc_client.go`) to MemeService.
- Caching layer (TODO).

c. MemeService (Go)
- Docker container from `services/meme-service.Dockerfile`.
- gRPC server defined by `services/proto/memeService/meme.proto`.
- Handles DB CRUD for memes, stores metadata in PostgreSQL, writes image files to mounted volume.
- Internal packages: `db` (config + queries), `server` (gRPC handlers), `utils`.

d. PostgreSQL
- Container from `services/postgres.Dockerfile`.
- Initialized with `init.sql`.
- Stores tables for memes, tags, users (future).

e. Shared File Storage
- Mounted volume accessible by MemeService (for writes) and Gateway (for reads).
- Stores raw image files and generated meme variants.

f. Auxiliary Services (future or library form)
- Moderator (`services/moderator/moderator.go`): CLI or service for offensive‐content scanning (OCR, image analysis).
- Queue (`services/queue/queue.go`): for async tasks (e.g., thumbnail generation).
- Rate Limiter modules under `services/rate-limiter`.

g. Protocol Definitions
- `services/proto/memeService`: central gRPC contract shared by Gateway and MemeService.

##### Interactions & Data Flow
1. User → Browser: UI loaded (SSR/static)
2. Browser → Gateway: HTTP(S) REST calls (upload, search, delete, update)
3. Gateway → Rate Limiter & Auth → Validation → Caching lookup
4. Gateway → MemeService: gRPC request/response
5. MemeService → PostgreSQL: SQL queries
6. MemeService → File System: write/read image files
7. Gateway → File System: serve images to client
8. Optional: Gateway enqueues tasks to Queue or invokes Moderator for content filtering.

##### Architectural Patterns & Principles
- Microservice decomposition: each service has single responsibility.
- API Gateway pattern: central entry to enforce auth, rate limiting, validation.
- Internal modularization in Go via `/cmd`, `/internal`.
- Next.js App Router with localized dynamic routes.
- Contract‐first design: gRPC proto for internal comms.
- Docker Compose orchestration sample under `services/docker-compose.yml.sample`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef frontend fill:#E0F7FA,stroke:#006064
    classDef gateway fill:#C8E6C9,stroke:#2E7D32
    classDef service fill:#FFE0B2,stroke:#EF6C00
    classDef db fill:#E1BEE7,stroke:#6A1B9A
    classDef storage fill:#B0BEC5,stroke:#546E7A
    classDef optional fill:#ffffff,stroke:#757575,stroke-dasharray:5 5

    User["User (Browser)"]:::frontend
    Client["Next.js Client"]:::frontend
    User -->|loads UI| Client
    Client -->|HTTP/REST| GW

    click Client "https://github.com/bassemhalim/memedb/tree/master/client/"

    subgraph "Services (Docker Compose)"
        direction TB

        subgraph "API Gateway"
            direction TB
            GW["API Gateway\n(Go)\nREST"]:::gateway
            Auth["Auth (JWT)"]:::gateway
            RL["Rate Limiter"]:::gateway
            MW["Validation Middleware"]:::gateway
            FS["FileServer"]:::gateway
            GC["gRPC Client"]:::gateway
            GW_CORE["Server & Utils"]:::gateway

            GW --> Auth
            GW --> RL
            GW --> MW
            GW --> FS
            GW --> GC
            GW --> GW_CORE

            click GW "https://github.com/bassemhalim/memedb/blob/master/services/gateway/cmd/memes_api/main.go"
            click Auth "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/auth/auth.go"
            click RL "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/middleware/middleware.go"
            click MW "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/middleware/middleware.go"
            click FS "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/fileserver/server.go"
            click GC "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/server/grpc_client.go"
            click GW_CORE "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/server/server.go"
            click GW_CORE "https://github.com/bassemhalim/memedb/blob/master/services/gateway/internal/server/utils.go"
        end

        subgraph "MemeService"
            direction TB
            MS["MemeService\n(Go)\ngRPC Server"]:::service
            DBInit["init.sql"]:::service
            DB["DB Config & Queries"]:::service
            MS_SRV["gRPC Handlers"]:::service
            MS_UTIL["Utils"]:::service

            MS --> DBInit
            MS --> DB
            MS --> MS_SRV
            MS --> MS_UTIL

            click MS "https://github.com/bassemhalim/memedb/blob/master/services/meme-service.Dockerfile"
            click MS "https://github.com/bassemhalim/memedb/blob/master/services/memeService/cmd/memeservice/server.go"
            click DBInit "https://github.com/bassemhalim/memedb/blob/master/services/memeService/init.sql"
            click DB "https://github.com/bassemhalim/memedb/blob/master/services/memeService/internal/db/config.go"
            click MS_SRV "https://github.com/bassemhalim/memedb/blob/master/services/memeService/internal/server/server.go"
            click MS_UTIL "https://github.com/bassemhalim/memedb/blob/master/services/memeService/internal/utils/utils.go"
        end

        Pg["PostgreSQL"]:::db
        click Pg "https://github.com/bassemhalim/memedb/blob/master/services/postgres.Dockerfile"

        Stg["Shared Storage"]:::storage

        GW -->|HTTP/REST| GW
        Client -->|HTTP/REST| GW
        GW -->|gRPC| MS
        MS -->|gRPC| GW
        MS -->|SQL| Pg
        MS -->|FS I/O| Stg
        GW -->|FS I/O| Stg
    end

    Proto["Proto Contract"]:::service
    click Proto "https://github.com/bassemhalim/memedb/blob/master/services/proto/memeService/meme.proto"
    GW --> Proto
    MS --> Proto

    subgraph "Auxiliary Services (Optional)"
        direction TB
        Queue["Queue"]:::optional
        Mod["Moderator"]:::optional

        click Queue "https://github.com/bassemhalim/memedb/blob/master/services/queue/queue.go"
        click Mod "https://github.com/bassemhalim/memedb/blob/master/services/moderator/moderator.go"
    end

    GW -.->|enqueue tasks| Queue
    GW -.->|invoke| Mod
```
