How the system is built

PlugZero Analytics is built as two separate parts that talk to each other. We do this to keep the “heavy math” on the server and the “visuals” in the browser.

Two separate repositories

We use two main codebases. They are connected by a standard API.

1. The Backend (plugzero_api)

This is a Django project. It does all the work that takes a lot of processing power.

• Location: /Users/arop/Projects/plugzero/plugzero_api
• What it does: It handles user accounts, talks to the database (PostgreSQL), and runs the AI models.
• The rule: If it involves logic that doesn’t change based on what the user is clicking right now, it belongs here.

2. The Frontend (plugzero-analytics)

This is a Next.js project. It is responsible for what the user sees.

• Location: /Users/arop/Projects/plugzero/plugzero-analytics
• What it does: It draws the charts, handles the buttons, and makes sure the site feels fast.
• The rule: If it involves showing data or reacting to a mouse click, it belongs here.

How they talk to each other

The frontend and backend communicate using JSON over HTTPS.

• No sessions on the server: The server doesn’t remember who is logged in between requests.
• Tokens (JWT): Every time the frontend asks the backend for data, it sends a secret token (a JWT).
• The API structure: We use common paths like /api/projects/ or /api/analysis/. You can find a full list in the API Specification section.

Handling slow tasks

Some things, like scanning 1,000 pages of a website for SEO, take a long time. We don’t want the user to see a loading spinner for 5 minutes.

1. The user clicks a button.
2. The backend says “I’m on it” and gives back a task_id.
3. The actual work happens in the background using a tool called Celery.
4. The frontend keeps checking (polling) that task_id until the work is finished.