# parisa-reza/seo-checker-parisa-reza architecture

> Architecture diagram of the GitHub repository parisa-reza/seo-checker-parisa-reza, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parisa-reza/seo-checker-parisa-reza
- Repository: https://github.com/parisa-reza/seo-checker-parisa-reza

## Overview

1. This repository is split into two deployable backends with a shared domain: a Django application for the user-facing audit workflow, and a Go service for the audit execution backend. The project appears to implement an SEO/audit checker.

2. The Django app lives under `django-app/` and is organized as a conventional Django project:
   - `config/` holds project settings, routing, WSGI/ASGI entrypoints.
   - `audits/` is the main Django app, containing models, views, admin, and migrations.
   - `templates/audits/` contains the UI pages for the audit flow: home, loading, results, and history.

3. The Django side is the orchestration and presentation layer. Its templates suggest a multi-step flow:
   - start an audit from the home page,
   - show a loading state while work is in progress,
   - display results,
   - view audit history.
   This implies Django owns the browser-facing workflow and persistence for audit records.

4. The Go service in `go-service/` is the computation/execution layer. It is split into:
   - `internal/crawler/` for fetching or traversing target sites,
   - `internal/analyzer/` for evaluating the crawled data,
   - `internal/handlers/` for HTTP endpoints,
   - `internal/routes/` for API route wiring,
   - `internal/models/` for request/response or domain structs.
   This strongly suggests the Go service performs the heavy-lift audit work and exposes an API consumed by Django.

5. The main data flow is likely:
   - user starts an audit in Django,
   - Django sends the target URL or audit parameters to the Go API,
   - Go crawls/analyzes the site and returns structured findings,
   - Django stores the audit/result data in its database and renders the results page.
   The presence of a loading template reinforces that audits are asynchronous or at least long-running from the user’s perspective.

6. Persistence is centered in Django. The `audits` app includes database migrations, so it defines the primary schema for audit records and results. Admin support in `audits/admin.py` indicates operators can inspect or manage audits through the Django admin interface.

7. The Go service appears stateless from the tree: there are no migrations or database directories on the Go side. That means it likely acts as an API worker/service, with state handled upstream by Django or passed through request/response payloads.

8. The repo includes `docs/api-spec.md`, which is a useful boundary artifact: it likely documents the contract between Django and the Go service. For architecture diagrams, this contract is the main integration seam between the two runtimes.

9. Runtime and deployment are split:
   - Django runs on Python with `manage.py`, `settings.py`, and `runserver` for local development.
   - Go service runs independently with `go run .`.
   - `docker-compose.yml` suggests there is at least some containerized local environment supporting one or both services.

10. The root `.env.example` implies environment-based configuration for secrets and service endpoints. In practice, this likely includes Django settings and the address of the Go API so the two services can talk without hardcoding values.

11. The architecture has a clear boundary between presentation/orchestration and analysis:
   - Django: HTTP/UI, audit lifecycle, persistence, history/results views.
   - Go: crawler/analyzer API, domain-specific processing.
   This separation is the key structural feature of the repository.

12. For a diagram, the most important elements are:
   - Browser/user
   - Django web app
   - Django database
   - Go audit API service
   - External target websites being crawled
   The arrows should show Django coordinating requests to the Go service, the Go service fetching external sites, and Django persisting and displaying outcomes.

Main entry points: [`django-app/audits/views.py`](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/views.py) (Audit flow), [`go-service/internal/handlers/audit_handler.go`](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/handlers/audit_handler.go) (Audit handler), [`go-service/internal/crawler/crawler.go`](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/crawler/crawler.go) (Crawler), [`go-service/internal/routes/routes.go`](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/routes/routes.go) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_django["Django app"]
  node_node_home["Home<br/>template<br/>[home.html]"]
  node_node_loading["Loading<br/>template<br/>[loading.html]"]
  node_node_results["Results<br/>template<br/>[results.html]"]
  node_node_history["History<br/>template<br/>[history.html]"]
  node_node_django_views["Audit flow<br/>orchestration<br/>[views.py]"]
  node_node_django_models[("Audit data<br/>persistence<br/>[models.py]")]
  node_node_django_admin["Admin<br/>ops-ui<br/>[admin.py]"]
  node_node_django_urls["URL config<br/>routing<br/>[urls.py]"]
  node_node_django_settings["Settings<br/>config<br/>[settings.py]"]
  node_node_django_entry["Manage<br/>entrypoint<br/>[manage.py]"]
end

subgraph group_group_go["Go service"]
  node_node_go_entry["Main<br/>entrypoint<br/>[main.go]"]
  node_node_go_routes["Routes<br/>routing<br/>[routes.go]"]
  node_node_go_handler["Audit handler<br/>http<br/>[audit_handler.go]"]
  node_node_go_crawler["Crawler<br/>fetcher<br/>[crawler.go]"]
  node_node_go_analyzer["Analyzer<br/>engine<br/>[analyzer.go]"]
  node_node_go_models["API models<br/>schema<br/>[models.go]"]
end

subgraph group_group_boundary["Shared boundary"]
  node_node_api_spec["API spec<br/>contract<br/>[api-spec.md]"]
  node_node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
end

node_node_browser(("User<br/>actor"))
node_node_db[("Database<br/>store")]
node_node_sites(("Target sites<br/>external"))

node_node_browser -->|"starts audit"| node_node_home
node_node_home -->|"submit"| node_node_django_views
node_node_django_views -->|"pending state"| node_node_loading
node_node_django_views -->|"calls API"| node_node_go_handler
node_node_go_routes -->|"dispatches"| node_node_go_handler
node_node_go_handler -->|"crawl"| node_node_go_crawler
node_node_go_crawler -->|"fetches"| node_node_sites
node_node_go_crawler -->|"passes data"| node_node_go_analyzer
node_node_go_analyzer -->|"emits findings"| node_node_go_models
node_node_go_handler -->|"returns result"| node_node_django_views
node_node_django_views -->|"persist"| node_node_django_models
node_node_django_models -->|"save/load"| node_node_db
node_node_django_views -->|"render"| node_node_results
node_node_django_views -->|"render"| node_node_history
node_node_django_views -.->|"manage"| node_node_django_admin
node_node_django_urls -->|"routes"| node_node_django_views
node_node_django_entry -->|"bootstraps"| node_node_django_settings
node_node_go_entry -->|"boots"| node_node_go_routes
node_node_api_spec -.->|"defines contract"| node_node_go_routes
node_node_api_spec -.->|"defines contract"| node_node_django_views
node_node_compose -.->|"runs"| node_node_django_entry
node_node_compose -.->|"runs"| node_node_go_entry

click node_node_home "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/home.html"
click node_node_loading "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/loading.html"
click node_node_results "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/results.html"
click node_node_history "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/history.html"
click node_node_django_views "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/views.py"
click node_node_django_models "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/models.py"
click node_node_django_admin "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/admin.py"
click node_node_django_urls "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/config/urls.py"
click node_node_django_settings "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/config/settings.py"
click node_node_django_entry "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/manage.py"
click node_node_go_entry "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/main.go"
click node_node_go_routes "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/routes/routes.go"
click node_node_go_handler "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/handlers/audit_handler.go"
click node_node_go_crawler "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/crawler/crawler.go"
click node_node_go_analyzer "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/analyzer/analyzer.go"
click node_node_go_models "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/models/models.go"
click node_node_api_spec "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/docs/api-spec.md"
click node_node_compose "https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_home,node_node_loading,node_node_results,node_node_history,node_node_django_views,node_node_django_models,node_node_django_admin,node_node_django_urls,node_node_django_settings,node_node_django_entry toneBlue
class node_node_go_entry,node_node_go_routes,node_node_go_handler,node_node_go_crawler,node_node_go_analyzer,node_node_go_models toneAmber
class node_node_api_spec,node_node_compose toneMint
class node_node_browser,node_node_db,node_node_sites toneNeutral
```

## Components

### Django app

Browser-facing audit workflow, persistence, and admin.

- [Home](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/home.html): template · Entry point for starting a new audit. · `django-app/templates/audits/home.html`
- [Loading](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/loading.html): template · Waiting state while audit work runs. · `django-app/templates/audits/loading.html`
- [Results](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/results.html): template · Rendered audit findings and scores. · `django-app/templates/audits/results.html`
- [History](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/templates/audits/history.html): template · Past audits and prior results. · `django-app/templates/audits/history.html`
- [Audit flow](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/views.py): orchestration · Coordinates submit, polling, results, and history views. · `django-app/audits/views.py`
- [Audit data](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/models.py): persistence · Audit and audit-result domain models backed by migrations. · `django-app/audits/models.py`
- [Admin](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/audits/admin.py): ops-ui · Django admin inspection and management of audits. · `django-app/audits/admin.py`
- [URL config](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/config/urls.py): routing · Project URL routing into the audits app. · `django-app/config/urls.py`
- [Settings](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/config/settings.py): config · Django project settings and environment wiring. · `django-app/config/settings.py`
- [Manage](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/django-app/manage.py): entrypoint · Local Django runtime entrypoint. · `django-app/manage.py`

### Go service

Audit execution API with crawl/analyze pipeline.

- [Main](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/main.go): entrypoint · Go service startup and server bootstrap. · `go-service/main.go`
- [Routes](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/routes/routes.go): routing · HTTP route wiring for the audit API. · `go-service/internal/routes/routes.go`
- [Audit handler](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/handlers/audit_handler.go): http · API endpoint layer that accepts audit requests and returns responses. · `go-service/internal/handlers/audit_handler.go`
- [Crawler](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/crawler/crawler.go): fetcher · Traverses or fetches target sites for audit input. · `go-service/internal/crawler/crawler.go`
- [Analyzer](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/analyzer/analyzer.go): engine · Evaluates crawled data and produces findings. · `go-service/internal/analyzer/analyzer.go`
- [API models](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/go-service/internal/models/models.go): schema · Request, response, and domain structs for the service. · `go-service/internal/models/models.go`

### Shared boundary

Deployment and contract artifacts connecting the two runtimes.

- [API spec](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/docs/api-spec.md): contract · Documentation for the Django-to-Go integration boundary. · `docs/api-spec.md`
- [Compose](https://github.com/parisa-reza/seo-checker-parisa-reza/blob/main/docker-compose.yml): deployment · Local multi-service runtime orchestration. · `docker-compose.yml`

### Other components

- **User**: actor · Starts audits and views progress and results.
- **Database**: store · Primary persistence for audits and results.
- **Target sites**: external · Websites analyzed by the crawler.

## Connections

- User → Home: starts audit · The user begins a new audit from the home page.
- Home → Audit flow: submit · The home page sends the audit request into Django orchestration.
- Audit flow → Loading: pending state · Django renders a loading view while work is in progress.
- Audit flow → Audit handler: calls API · Django sends the audit target and parameters to the Go service.
- Routes → Audit handler: dispatches · Go routes incoming API traffic to the audit handler.
- Audit handler → Crawler: crawl · The handler triggers site crawling.
- Crawler → Target sites: fetches · Crawler visits the target website(s).
- Crawler → Analyzer: passes data · Crawled content is forwarded for analysis.
- Analyzer → API models: emits findings · Analyzer produces structured audit results.
- Audit handler → Audit flow: returns result · Structured findings are returned to Django.
- Audit flow → Audit data: persist · Django stores audits and results in its domain model.
- Audit data → Database: save/load · Audit records are persisted in the database.
- Audit flow → Results: render · Results page shows the completed audit output.
- Audit flow → History: render · History page shows prior audit runs.
- Audit flow → Admin: manage · Admin supports operator inspection and maintenance.
- URL config → Audit flow: routes · Project URL config routes requests into the audits workflow.
- Manage → Settings: bootstraps · Manage.py loads project settings for local execution.
- Main → Routes: boots · Go main initializes HTTP routing.
- API spec → Routes: defines contract · API documentation captures the service boundary.
- API spec → Audit flow: defines contract · The same contract guides Django's API calls.
- Compose → Manage: runs · Compose can launch the Django service.
- Compose → Main: runs · Compose can launch the Go service.
