# yammerjp/awkblog architecture

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

- Interactive diagram: https://gitdiagram.com/yammerjp/awkblog
- Repository: https://github.com/yammerjp/awkblog

## Overview

##### Main Components
- AWK Application Server – Represents the core business logic. This is largely located in the src directory (with controllers handling various HTTP methods, middleware functions, models for data handling, and supporting libraries in src/lib). The entrypoint (src/entrypoint.awk) initializes the process.
- Frontend/Presentation Layer – Includes static files and page views (located in the view and static directories). This layer is responsible for serving HTML pages, CSS, JavaScript, and internationalization (e.g., view/i18n).
- Reverse Proxy (Nginx) – Managed by configuration templates (found in misc/nginx.default.conf.template and bin/build_nginx_conf.sh), which serves as the front door to the AWK backend while handling static content.
- Database – PostgreSQL is used as the backend data store (schema.sql indicates the database schema). The AWK app interacts with it via the pgsql.awk library.
- External Authentication – GitHub OAuth integration, enabling user login and authorization.
- Optional External Services – Amazon S3 integration for image uploads (based on src/lib/awss3.awk and related AWS configuration environment variables).
- Containerization & Deployment – Docker is used to containerize the system (Dockerfile, docker-compose.yml, and various shell scripts in the bin directory) to facilitate deployment and testing.

##### Relationships and Data Flow
- Client Interaction: Web browsers reach the system through a reverse proxy (Nginx), which then routes requests to the AWK application server.
- AWK Application: It parses incoming HTTP requests (handled by controller scripts in src/controller and routed using src/lib/router.awk), calling middleware (in src/middleware) where applicable. These controllers determine functionality like rendering pages, processing form data, or handling API calls.
- Database Communication: When required, the AWK application interacts with PostgreSQL (using src/lib/pgsql.awk and the schema defined in schema.sql) to retrieve or store blog posts, account information, etc.
- OAuth Interaction: During authentication, the application reaches out to GitHub’s OAuth endpoints. The application processes and validates responses using supported libraries.
- Image Uploads: Optionally, if image uploads are enabled and AWS credentials are configured, the AWK application uses Amazon S3 (through src/lib/awss3.awk) for image storage.

##### Architectural Patterns and Design Principles
- Modularity: The project is organized into clear components (controllers, models, middleware, libraries) ensuring separation of concerns.
- Script-based Routing & Handling: The application uses AWK’s scripting power to process HTTP requests in a somewhat “RESTful” manner.
- Containerized Deployment: Docker files, compose files, and shell scripts indicate an infrastructure that is easy to set up, test, and deploy.
- Test & Validation Layers: Integration and unit tests are present in the test directory, emphasizing the reliability and correctness of the system.

– Use clear, descriptive labels for each component (e.g., “AWK Blog Controller,” “Markdown Processor,” “OAuth Module”).
– Indicate interdependencies or integration points such as the middleware’s role in authentication, template rendering, and error handling.
– Optionally add annotations about environment configuration (drawing attention to the use of .env and environment variables for setting up OAuth, AWS S3, etc.).
– Include Docker as an encompassing layer that shows how these components are orchestrated for development/deployment.

##### Additional Details
– Emphasize that the architecture highlights AWK’s unusual but powerful use in building a full-blown web application.
– Reflect on the modularity achieved by splitting functionalities among multiple directories (src/controller, src/model, src/lib, etc.) and how tests (in test) validate the integration.
– While it might be tempting to lump things together, strive for granularity: split out each part (e.g., authentication, routing, database interactions) to capture dependencies and inter-component communications fully.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        WB["Web Browser"]:::client
    end

    subgraph "Gateway Layer"
        NG["Nginx Reverse Proxy"]:::gateway
        NG1["Nginx Config Template"]:::gateway
        NG2["Nginx Config Builder"]:::gateway
    end

    subgraph "Application Layer"
        AWK["AWK Application Server"]:::app
        subgraph "App Components"
            EP["Entry Point"]:::app
            CT["Controllers"]:::app
            MW["Middleware"]:::app
            LB["Supporting Libraries"]:::app
        end
    end

    subgraph "Presentation Layer"
        FE["Static Files & Views"]:::frontend
        ST["Static Files"]:::frontend
        PV["Page Views & Templates"]:::frontend
    end

    subgraph "Data & External"
        DB["PostgreSQL Database"]:::database
        DB1["Database Schema"]:::database
        DB2["PostgreSQL Library"]:::database

        OA["GitHub OAuth"]:::external
        OA1["GitHub OAuth Library"]:::external
        OA2["OAuth Callback Controller"]:::external

        S3["Amazon S3"]:::external
        S3_["AWS S3 Integration"]:::external
    end

    subgraph "Deployment & Setup"
        DT["Docker Container"]:::deployment
        DF["Dockerfile"]:::deployment
        DC["Docker Compose"]:::deployment
        DS["Deployment Setup Script"]:::deployment
        SS["Start Script"]:::deployment
    end

    WB -->|"sendsRequest"| NG
    NG -->|"forwardsRequest"| AWK
    NG -->|"servesStatic"| FE
    NG --> NG1
    NG --> NG2

    AWK -.-> EP
    AWK -.-> CT
    AWK -.-> MW
    AWK -.-> LB

    AWK -->|"interacts_with"| DB
    AWK -->|"authenticates_via"| OA
    AWK -->|"uploads_to"| S3

    DB --> DB1
    DB --> DB2

    OA --> OA1
    OA --> OA2

    S3 --> S3_

    FE --> ST
    FE --> PV

    DT -->|"containers"| AWK
    DT -->|"containers"| NG
    DT -->|"containers"| DB
    DT -->|"containers"| FE

    DT --> DF
    DT --> DC
    DT --> DS
    DT --> SS

    classDef client fill:#b3cde0,stroke:#000,stroke-width:2px;
    classDef gateway fill:#fdbb84,stroke:#000,stroke-width:2px;
    classDef app fill:#ccebc5,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ffffb3,stroke:#000,stroke-width:2px;
    classDef database fill:#80b1d3,stroke:#000,stroke-width:2px;
    classDef external fill:#decbe4,stroke:#000,stroke-width:2px;
    classDef deployment fill:#d9d9d9,stroke:#000,stroke-width:2px;

    click EP "https://github.com/yammerjp/awkblog/blob/main/src/entrypoint.awk"
    click CT "https://github.com/yammerjp/awkblog/tree/main/src/controller"
    click MW "https://github.com/yammerjp/awkblog/tree/main/src/middleware"
    click LB "https://github.com/yammerjp/awkblog/tree/main/src/lib"
    click ST "https://github.com/yammerjp/awkblog/tree/main/static"
    click PV "https://github.com/yammerjp/awkblog/tree/main/view"
    click NG1 "https://github.com/yammerjp/awkblog/blob/main/misc/nginx.default.conf.template"
    click NG2 "https://github.com/yammerjp/awkblog/blob/main/bin/build_nginx_conf.sh"
    click DB1 "https://github.com/yammerjp/awkblog/blob/main/schema.sql"
    click DB2 "https://github.com/yammerjp/awkblog/blob/main/src/lib/pgsql.awk"
    click OA1 "https://github.com/yammerjp/awkblog/blob/main/src/lib/github.awk"
    click OA2 "https://github.com/yammerjp/awkblog/blob/main/src/controller/oauth_callback.GET.awk"
    click S3_ "https://github.com/yammerjp/awkblog/blob/main/src/lib/awss3.awk"
    click DF "https://github.com/yammerjp/awkblog/tree/main/Dockerfile"
    click DC "https://github.com/yammerjp/awkblog/blob/main/compose.yml"
    click DS "https://github.com/yammerjp/awkblog/blob/main/bin/setup.sh"
    click SS "https://github.com/yammerjp/awkblog/blob/main/bin/start.sh"
```
