How parisa-reza/seo-checker-parisa-reza works
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: views.py Audit flow · audit_handler.go Audit handler · crawler.go Crawler · routes.go Routes
Components 21
Django app
Browser-facing audit workflow, persistence, and admin.
- Home · Entry point for starting a new audit.
django-app/templates/audits/home.html - Loading · Waiting state while audit work runs.
django-app/templates/audits/loading.html - Results · Rendered audit findings and scores.
django-app/templates/audits/results.html - History · Past audits and prior results.
django-app/templates/audits/history.html - Audit flow · Coordinates submit, polling, results, and history views.
django-app/audits/views.py - Audit data · Audit and audit-result domain models backed by migrations.
django-app/audits/models.py - Admin · Django admin inspection and management of audits.
django-app/audits/admin.py - URL config · Project URL routing into the audits app.
django-app/config/urls.py - Settings · Django project settings and environment wiring.
django-app/config/settings.py - Manage · Local Django runtime entrypoint.
django-app/manage.py
Go service
Audit execution API with crawl/analyze pipeline.
- Main · Go service startup and server bootstrap.
go-service/main.go - Routes · HTTP route wiring for the audit API.
go-service/internal/routes/routes.go - Audit handler · API endpoint layer that accepts audit requests and returns responses.
go-service/internal/handlers/audit_handler.go - Crawler · Traverses or fetches target sites for audit input.
go-service/internal/crawler/crawler.go - Analyzer · Evaluates crawled data and produces findings.
go-service/internal/analyzer/analyzer.go - API models · Request, response, and domain structs for the service.
go-service/internal/models/models.go
Shared boundary
Deployment and contract artifacts connecting the two runtimes.
Other components
- User · Starts audits and views progress and results.
- Database · Primary persistence for audits and results.
- Target sites · Websites analyzed by the crawler.
Connections 22
- 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.