# ndzuma/mywebsiteapi architecture

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

- Interactive diagram: https://gitdiagram.com/ndzuma/mywebsiteapi
- Repository: https://github.com/ndzuma/mywebsiteapi

## Overview

##### Project Type and Purpose
- This is primarily a RESTful backend API written in Go using the Echo framework, augmented by a single static admin UI (`web/admin.html`).
- Its purpose is to manage portfolio projects stored in a PostgreSQL database, expose CRUD endpoints under `/api/projects`, and serve a minimal admin panel at `/admin`.

##### File Structure
- **api/main.go**: Application entry-point. Sets up Echo router, middleware (Basic Auth), and route registration.
- **internal/handlers/**: HTTP handlers for each resource (`projects.go`). Contains request parsing, response formatting, error handling.
- **internal/models/**: Domain models/data definitions (`project.go`).
- **internal/database/**: Database connection logic (`database.go`). Encapsulates opening a Postgres connection via env vars.
- **pkg/config.go**: Configuration loader (reads env vars such as DATABASE_URL, API_USERNAME/PASSWORD, MODE, PORT).
- **web/admin.html**: Static HTML admin panel for project management UI.
- **railway.toml**, **.nixpacks.toml**: Deployment descriptors (Railway hosting, Nixpacks build instructions).
- **go.mod**, **go.sum**: Dependency management.

##### README for Additional Insights
- The README confirms routes, security (Basic Auth), environment variables, deployment on Railway using Nixpacks, and future plans (caching, JWT, rate-limiting, CI/CD).

##### Main Components & Their Interactions
a. **Client Layer**
- Browser-based Admin UI (static HTML/JS)
- CLI/Postman or any HTTP client for direct API consumption
b. **API Server Layer**
- Echo HTTP Server with middleware for Basic Auth and routing
- Configuration module (`pkg/config.go`)
- Handlers (`internal/handlers`) invoke business logic and database operations
c. **Persistence Layer**
- PostgreSQL database (hosted externally; URL injected via `DATABASE_URL`)
d. **Deployment/Infrastructure**
- Railway hosting environment
- Nixpacks build pipeline
- Environment variables store secrets and config

Interaction flow:
Client → HTTP (Basic Auth) → Echo Router → Handler → Model → Database → Handler → Response → Client

##### Architectural Patterns & Design Principles
- **Layered Architecture**:
- Presentation (static UI)
- API (handlers, routing)
- Domain Models
- Data Access (database package)
- **Separation of Concerns**: Config module separate from business logic; handlers contain HTTP glue, models define data, database package manages connections.
- **12-Factor App Principles**: Environment-based configuration, single codebase, stateless processes.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser UI"]:::client
        HTTPClient["HTTP Client\n(Postman/CLI)"]:::client
    end

    %% API Server
    subgraph "API Server"
        entry["Application Entry Point\n(main.go)"]:::app
        config["Configuration Module\n(pkg/config.go)"]:::config
        auth["Basic Auth Middleware"]:::app
        router["Echo Router"]:::app
        handlers["HTTP Handlers\nProjects CRUD"]:::app
        models["Domain Model\nProject"]:::app
        dbconn["Database Connector"]:::app
        static["Static Admin UI\n(admin.html)"]:::client
        deps["Dependencies\n(go.mod, go.sum)"]:::infra
    end

    %% Data Store
    DB["PostgreSQL Database"]:::data

    %% Infrastructure
    subgraph "Deployment & Build"
        railway["Railway Descriptor\n(railway.toml)"]:::infra
        nixpacks["Nixpacks Build Config\n(nixpacks.toml)"]:::infra
    end

    %% Connections
    Browser -->|"GET /admin.html\n(HTTP)"| entry
    entry -->|"serves"| static
    Browser -->|"BasicAuth + JSON\nGET/POST /api/projects"| entry
    HTTPClient -->|"BasicAuth + JSON\nGET/POST /api/projects"| entry

    entry -->|"loads config"| config
    entry --> auth
    auth --> router
    router --> handlers
    handlers --> models
    handlers --> dbconn
    dbconn -->|"SQL Queries\n(PSQL)"| DB
    dbconn --> handlers
    handlers --> router
    router --> HTTPClient
    router --> Browser

    %% Config injection
    InfraConfig(["Environment Variables"]):::infra
    InfraConfig -.-> config
    InfraConfig -.-> railway
    InfraConfig -.-> nixpacks

    %% Click Events
    click entry "https://github.com/ndzuma/mywebsiteapi/blob/main/api/main.go"
    click config "https://github.com/ndzuma/mywebsiteapi/blob/main/pkg/config.go"
    click handlers "https://github.com/ndzuma/mywebsiteapi/blob/main/internal/handlers/projects.go"
    click models "https://github.com/ndzuma/mywebsiteapi/blob/main/internal/models/project.go"
    click dbconn "https://github.com/ndzuma/mywebsiteapi/blob/main/internal/database/database.go"
    click static "https://github.com/ndzuma/mywebsiteapi/blob/main/web/admin.html"
    click deps "https://github.com/ndzuma/mywebsiteapi/blob/main/go.mod"
    click deps "https://github.com/ndzuma/mywebsiteapi/blob/main/go.sum"
    click railway "https://github.com/ndzuma/mywebsiteapi/blob/main/railway.toml"
    click nixpacks "https://github.com/ndzuma/mywebsiteapi/blob/main/nixpacks.toml"

    %% Styles
    classDef app fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef client fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef data fill:#FFF3E0,stroke:#F57C00,color:#E65100
    classDef infra fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef config fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
```
