# justanotherbyte/imoog architecture

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

- Interactive diagram: https://gitdiagram.com/justanotherbyte/imoog
- Repository: https://github.com/justanotherbyte/imoog

## Overview

##### Project type and purpose
- This is a backend service – a deployable, database-backed CDN node exposing an ASGI HTTP interface for file upload and retrieval. It uses PostgreSQL or MongoDB for persistence, and optionally Redis or in-memory cache for performance. It’s intended to sit behind a reverse proxy (e.g., NGINX) and optionally behind Cloudflare.

##### File structure
- Top-level:
- examples/ (NGINX and systemd config)
- imoog/ (application package)
- requirements.txt, README.md
- imoog/ contains:
- app.py – ASGI application entry point
- views.py – HTTP route handling (upload, fetch, metadata)
- cache/ – basecache.py, memorycache.py, rediscache.py
- database/ – drivers.py, postgres.py, mongo.py
- settings.py – all configurable options (DB URIs, auth key, cache policy)
- opengraph.py – optional metadata extractor
- No frontend code; this is a pure backend service.

##### Extract README insights
- ASGI server (Hypercorn or Uvicorn)
- Supports file uploads via multipart/form-data with an Authorization header
- Recommends proxying with NGINX and optionally Cloudflare in front
- Describes cache drivers and database drivers

##### Main architectural components
a. Client & CDN edge
- End users or upstream services requesting upload or download
- Optionally Cloudflare in front for global caching
b. Reverse proxy
- NGINX (examples/nginx.conf) – handles TLS, UDS/TCP, load balancing to ASGI
c. ASGI Application
- imoog.app – entry point invoked by Hypercorn/Uvicorn
- imoog.views – request routing and HTTP handlers
d. Caching layer
- imoog.cache.* – in-memory or Redis cache
- Cache lookup on GET; cache population on first fetch
e. Persistence layer
- imoog.database.* – abstraction over PostgreSQL (asyncpg) or MongoDB (motor)
- Stores file data and metadata
f. Auxiliary service
- opengraph.py – optional fetch of remote URL metadata (image previews)
g. Configuration
- settings.py – all runtime settings, credentials, driver choices

##### Relationships and data flow
- Client → (Cloudflare) → NGINX → ASGI app
- ASGI app → views.py
- POST /upload:
– Authorization check → view
– write to cache (optional) → write to database → respond with file_id
- GET /<file_id>:
– check cache → if hit, return
– else fetch from database → store in cache → return
- ASGI app → database driver → actual DB server
- ASGI app → cache driver → Redis or in-memory store

##### Architectural patterns and principles
- Layered architecture: Presentation (HTTP) → Business logic (views + opengraph) → Cache → Data access
- Dependency inversion via abstract base classes (basecache, drivers.py)
- Asynchronous I/O throughout for high concurrency

##### Final advice
- Be detailed: capture async boundaries, driver abstractions, and config injection
- Do not over-complicate: treat each Python module group as one component (cache, database, views)
- Runtime topology (client → proxy → ASGI → cache/db) rather than file paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Layer
    Client["End User / Upstream Service"]:::external
    Cloudflare((Cloudflare CDN)):::external
    Client -->|HTTPS| Cloudflare

    %% Edge / Proxy Layer
    NGINX["NGINX Reverse Proxy"]:::proxy
    Cloudflare -->|HTTPS| NGINX
    NGINX -->|UDS/TCP| ASGIApp

    %% Application Layer
    subgraph "Application Layer"
        ASGIApp["ASGI App\n(imoog/app.py)"]:::app
        Views["HTTP Route Handlers\n(imoog/views.py)"]:::app
        OpenGraph["OpenGraph Metadata Extractor\n(imoog/opengraph.py)"]:::app
        ASGIApp -->|Invokes| Views
        Views -->|Optional metadata fetch| OpenGraph
    end

    %% Cache Layer
    subgraph "Cache Abstraction"
        CacheBase["BaseCache Interface\n(imoog/cache/basecache.py)"]:::cache
        MemCache["In-Memory Cache\n(imoog/cache/memorycache.py)"]:::cache
        RedisCache["Redis Cache\n(imoog/cache/rediscache.py)"]:::cache
        CacheBase --> MemCache
        CacheBase --> RedisCache
    end
    Views -->|GET checks cache| CacheBase
    Views -->|POST writes cache| CacheBase
    CacheBase -->|Redis protocol| RedisCache
    CacheBase -->|Memory access| MemCache

    %% Persistence Layer
    subgraph "Database Abstraction"
        DBDrivers["DB Interface\n(imoog/database/drivers.py)"]:::db
        Postgres["PostgreSQL Driver\n(imoog/database/postgres.py)"]:::db
        MongoDB["MongoDB Driver\n(imoog/database/mongo.py)"]:::db
        DBDrivers --> Postgres
        DBDrivers --> MongoDB
    end
    Views -->|persist/fetch| DBDrivers
    DBDrivers -->|PostgreSQL wire| Postgres
    DBDrivers -->|MongoDB wire| MongoDB

    %% Configuration
    Settings["Configuration Settings\n(imoog/settings.py)"]:::config
    Settings -.-> ASGIApp
    Settings -.-> CacheBase
    Settings -.-> DBDrivers

    %% Deployment Artifacts
    subgraph "Deployment Artifacts"
        NginxConf["NGINX Config\n(examples/imoog.conf)"]:::artifact
        Systemd["Systemd Service\n(examples/imoog.service)"]:::artifact
    end

    %% Documentation
    README["Project Documentation\n(README.md)"]:::artifact
    Requirements["Python Dependencies\n(requirements.txt)"]:::artifact

    %% Click Events
    click NginxConf "https://github.com/justanotherbyte/imoog/blob/main/examples/imoog.conf"
    click Systemd "https://github.com/justanotherbyte/imoog/blob/main/examples/imoog.service"
    click ASGIApp "https://github.com/justanotherbyte/imoog/blob/main/imoog/app.py"
    click Views "https://github.com/justanotherbyte/imoog/blob/main/imoog/views.py"
    click CacheBase "https://github.com/justanotherbyte/imoog/blob/main/imoog/cache/basecache.py"
    click MemCache "https://github.com/justanotherbyte/imoog/blob/main/imoog/cache/memorycache.py"
    click RedisCache "https://github.com/justanotherbyte/imoog/blob/main/imoog/cache/rediscache.py"
    click DBDrivers "https://github.com/justanotherbyte/imoog/blob/main/imoog/database/drivers.py"
    click Postgres "https://github.com/justanotherbyte/imoog/blob/main/imoog/database/postgres.py"
    click MongoDB "https://github.com/justanotherbyte/imoog/blob/main/imoog/database/mongo.py"
    click OpenGraph "https://github.com/justanotherbyte/imoog/blob/main/imoog/opengraph.py"
    click Settings "https://github.com/justanotherbyte/imoog/blob/main/imoog/settings.py"
    click README "https://github.com/justanotherbyte/imoog/blob/main/README.md"
    click Requirements "https://github.com/justanotherbyte/imoog/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#bbdefb,stroke:#1e88e5,color:#1e88e5,stroke-width:1px;
    classDef proxy fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32,stroke-width:1px;
    classDef app fill:#ffe0b2,stroke:#ef6c00,color:#ef6c00,stroke-width:1px;
    classDef cache fill:#fff9c4,stroke:#fbc02d,color:#fbc02d,stroke-width:1px;
    classDef db fill:#d7ccc8,stroke:#5d4037,color:#5d4037,stroke-width:1px;
    classDef config fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a,stroke-width:1px;
    classDef artifact fill:#f0f4c3,stroke:#7cb342,color:#7cb342,stroke-width:1px;
```
