# stjudewashere/seonaut architecture

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

- Interactive diagram: https://gitdiagram.com/stjudewashere/seonaut
- Repository: https://github.com/stjudewashere/seonaut

## Overview

##### Project type and purpose
- SEOnaut is a full-stack, monolithic web application written in Go.
- Purpose: crawl and audit websites for SEO issues, store results in a MySQL database, and present an interactive dashboard (using custom CSS/vanilla JS + Apache ECharts) to end users.

##### File structure
- Top-level components:
- cmd/server: entrypoint (main.go) that wires up HTTP server, services, repository, migrations.
- internal/: Go packages organized by feature/layer (archiver, crawler, issues, models, repository, routes, services, urlutils).
- web/: static assets (CSS, fonts, robots.txt) and HTML templates for server-side rendering.
- migrations/: SQL migrations for schema evolution.
- docker-compose.yml / Dockerfile: container orchestration and packaging.
- Patterns:
- Layered architecture (HTTP → routes → services → repository → MySQL).
- Modular feature groups (crawler engine, issue detectors, archiver).
- Single Go binary + Docker-deployed MySQL container.

##### README for additional insights
- Confirms Go + MySQL stack, Docker-based deployment, port 9000 HTTP interface, recommendation for HTTPS via reverse proxy.
- Hosted version uses same architecture (Go app container + MySQL).

##### Detail
- Routes
- Services (crawler, archiver, parser, issue detector, renderer)
- Repository
- Config & utils
- Essential modules without over-aggregating.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef datastore fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px

    Browser["Client Browser"]:::ui
    ReverseProxy["Reverse Proxy / Load Balancer"]:::backend

    subgraph "Docker Deployment"
        direction TB
        subgraph "SEOnaut Go App Container"
            direction TB
            Entrypoint["Entrypoint (main.go)"]:::backend
            Config["Configuration Loader"]:::backend
            URLUtils["URL Utilities"]:::backend
            subgraph "Web Assets"
                CSS["CSS (Static Assets)"]:::ui
                Fonts["Fonts"]:::ui
                StaticFiles["robots.txt"]:::ui
                Templates["HTML Templates"]:::ui
            end
            subgraph "Application Layers"
                direction TB
                Routes["Routes Layer"]:::backend
                Services["Service Layer"]:::backend
                Repository["Repository Layer"]:::backend
            end
            subgraph "Domain Modules"
                direction TB
                Archiver["Archiver Module"]:::backend
                Crawler["Crawler Engine"]:::backend
                Issues["Issue Detectors"]:::backend
                Models["Data Models"]:::backend
            end
            Migrations["SQL Migrations"]:::backend
            DockerfileNode["Dockerfile"]:::backend
        end

        subgraph "MySQL Container"
            MySQL["MySQL Database"]:::datastore
        end
    end

    External["External Websites (Target Domains)"]:::external

    Browser -->|"HTTPS / HTTP"| ReverseProxy
    ReverseProxy -->|"Forwards Requests"| Entrypoint
    Entrypoint -->|"loads"| Config
    Entrypoint -->|"initializes"| URLUtils
    Entrypoint -->|"runs migrations"| Migrations
    Entrypoint -->|"serves assets"| CSS
    Entrypoint -->|"serves assets"| Fonts
    Entrypoint -->|"serves"| StaticFiles
    Entrypoint -->|"renders"| Templates
    Entrypoint -->|"routes requests"| Routes

    Routes -->|calls| Services
    Services -->|uses| Repository
    Repository -->|queries| MySQL
    Services -->|crawls| External
    Services -->|archives data via| Archiver
    Services -->|detects issues via| Issues
    Services -->|manages data models| Models
    DockerfileNode -->|builds image| Entrypoint
    MySQL -- "Docker network" --> Entrypoint

    class Browser,CSS,Fonts,StaticFiles,Templates ui
    class ReverseProxy,Entrypoint,Config,URLUtils,Routes,Services,Repository,Archiver,Crawler,Issues,Models,Migrations,DockerfileNode backend
    class MySQL datastore
    class External external

    click Entrypoint "https://github.com/stjudewashere/seonaut/blob/main/cmd/server/main.go"
    click Routes "https://github.com/stjudewashere/seonaut/tree/main/internal/routes"
    click Services "https://github.com/stjudewashere/seonaut/tree/main/internal/services"
    click Repository "https://github.com/stjudewashere/seonaut/tree/main/internal/repository"
    click Config "https://github.com/stjudewashere/seonaut/blob/main/internal/config/config.go"
    click URLUtils "https://github.com/stjudewashere/seonaut/blob/main/internal/urlutils/absoluteurl.go"
    click Archiver "https://github.com/stjudewashere/seonaut/tree/main/internal/archiver"
    click Crawler "https://github.com/stjudewashere/seonaut/tree/main/internal/crawler"
    click Issues "https://github.com/stjudewashere/seonaut/tree/main/internal/issues"
    click Models "https://github.com/stjudewashere/seonaut/tree/main/internal/models"
    click Migrations "https://github.com/stjudewashere/seonaut/blob/main/migrations/*.up.sql and migrations/*.down.sql"
    click CSS "https://github.com/stjudewashere/seonaut/tree/main/web/css"
    click Fonts "https://github.com/stjudewashere/seonaut/tree/main/web/fonts"
    click StaticFiles "https://github.com/stjudewashere/seonaut/blob/main/web/static/robots.txt"
    click Templates "https://github.com/stjudewashere/seonaut/tree/main/web/templates"
    click DockerfileNode "https://github.com/stjudewashere/seonaut/tree/main/Dockerfile"
    click ReverseProxy "https://github.com/stjudewashere/seonaut/blob/main/docker-compose.yml"
    click DockerfileNode "https://github.com/stjudewashere/seonaut/tree/main/Makefile"
    click DockerfileNode "https://github.com/stjudewashere/seonaut/blob/main/docker-compose.yml"
    click Entrypoint "https://github.com/stjudewashere/seonaut/tree/main/Makefile"
    click External "https://github.com/stjudewashere/seonaut/blob/main/README.md"
```
