# ctrlne/cocopan-data-sales architecture

> Architecture diagram of the GitHub repository ctrlne/cocopan-data-sales, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ctrlne/cocopan-data-sales
- Repository: https://github.com/ctrlne/cocopan-data-sales

## Overview

This repository is a small full-stack application with a very clear three-tier shape:

1. Browser client
2. Node.js/Express backend
3. SQLite persistence layer

It also depends on two external AI/social APIs: Google Gemini and the Facebook Graph API.

#### High-level architecture

The app is centered around a dashboard for Cocopan marketing analysis. The browser UI lets a user log in, upload sales CSV data, inspect customer segments, view charts/tables, and request AI-generated recommendations or sentiment analysis. The backend mediates protected operations, talks to external APIs, and stores user/session/history data in SQLite.

There is no sign of a separate frontend build system or separate backend services. Everything appears to be in a single repository and likely deployed as one Node process serving static frontend assets plus API endpoints.

#### Main subsystems

##### 1) Frontend presentation layer
Files:
- `index.html`
- `style.css`
- `script.js`

Responsibilities:
- Render the dashboard UI in the browser.
- Handle user interaction such as login, CSV upload, analysis selection, and viewing results.
- Parse or pre-process uploaded sales data on the client side.
- Render charts and tables, likely using Chart.js.
- Call backend endpoints for authentication, analysis history, and external-data-driven features.

Important technologies from the README:
- Vanilla JavaScript
- HTML
- TailwindCSS for styling, though only `style.css` is present in the file tree
- Chart.js for visualization
- PapaParse for CSV parsing

Architecturally, this layer is the interaction and visualization boundary. It should not be considered the source of truth for authenticated state or stored history.

##### 2) Application/backend layer
Files:
- `server.js`

Responsibilities:
- Start the HTTP server, likely using Express.
- Serve the static frontend files.
- Expose API routes for login, session/auth handling, saving/retrieving analysis history, and AI/social integration.
- Validate and protect privileged operations using JWT.
- Interact with the database layer.
- Call external APIs using server-side secrets from environment variables.

Key backend responsibilities implied by the README:
- Authentication with JWT
- Password hashing via bcrypt
- Integration with Gemini API
- Integration with Facebook Graph API

This is the orchestration boundary: it receives requests from the browser, performs authentication and business logic, persists data, and fans out to external services.

##### 3) Data access / persistence layer
Files:
- `database.js`

Responsibilities:
- Encapsulate SQLite access.
- Define or manage the schema for users and analysis history.
- Provide a reusable interface for reads and writes from the backend.

From the README, persistence is used for:
- User accounts
- Saved analysis sessions/history

This is the storage boundary. Because SQLite is embedded, the persistence model is local to the server process rather than a separate database service.

#### External integrations

##### Google Gemini API
Used for:
- Generating strategic marketing recommendations
- Potentially assisting with sentiment analysis outputs

This is likely called from `server.js`, not from the browser, so the API key stays on the server.

##### Facebook Graph API
Used for:
- Fetching real-time comments from a Facebook business page
- Feeding those comments into a sentiment analysis workflow

This is also likely server-side to protect access tokens and avoid CORS/client exposure.

These integrations form a third-party services boundary. The app’s own data model likely transforms internal segment data or social comments into requests to these services, then stores or returns the generated results.

#### Data flows

##### A) Authentication flow
1. User submits login/register information in the browser.
2. Frontend sends credentials to the backend.
3. Backend hashes passwords with bcrypt and/or compares hashes for login.
4. On success, backend issues a JWT.
5. Frontend stores and sends the JWT with later requests.
6. Backend verifies JWT for protected endpoints.

This flow separates identity/session management from the UI.

##### B) Sales CSV analysis flow
1. User uploads a CSV file in the browser.
2. `script.js` likely parses it client-side with PapaParse.
3. Client computes or prepares customer metrics and RFM segment data.
4. The dashboard renders charts/tables from that processed data.
5. If the user saves the analysis, the resulting summary is sent to the backend.
6. Backend stores the analysis snapshot in SQLite for history/comparison.

The key architectural point is that CSV parsing and immediate visualization appear to happen in the client, while persistence happens on the server.

##### C) AI recommendation flow
1. The UI sends current segment data or an analysis summary to the backend.
2. Backend forwards a structured request to Gemini.
3. Gemini returns recommendations.
4. Backend returns the result to the frontend.
5. The frontend displays the recommendations in the dashboard.

This keeps the API key and prompt logic off the client.

##### D) Social sentiment flow
1. Backend fetches Facebook comments from the designated business page.
2. Comments are analyzed, likely using Gemini or another server-side sentiment routine.
3. Results are returned to the frontend for display.
4. Optionally, the sentiment snapshot may be saved in history.

Again, the browser is only the presentation layer; the sensitive tokens and API calls live on the server.

#### Important boundaries

##### Browser vs server boundary
The browser handles user interaction and visualization. The server handles trust-sensitive work:
- authentication
- secret-bearing API calls
- database writes
- history retrieval

This is the most important boundary in the repo.

##### Server vs persistence boundary
`server.js` should not directly embed persistence logic everywhere; `database.js` appears to isolate SQLite operations. That makes it the natural seam for diagramming the storage subsystem.

##### Internal data vs external API boundary
The app transforms internal business data into requests for Gemini/Facebook, then transforms responses back into dashboard-ready content. These integrations are not just “utilities”; they are first-class subsystems.

#### Likely runtime/deployment shape

Based on the file tree, this looks like:
- A Node.js process running Express
- Static assets served directly from the repo
- SQLite file stored locally with the app
- No separate frontend bundling pipeline
- No separate backend microservices

#### What to show in an architecture diagram

A good diagram for this repository would include:
- Browser client containing `index.html`, `style.css`, `script.js`
- Express/Node backend containing `server.js`
- SQLite database behind `database.js`
- Facebook Graph API and Google Gemini API as external services
- Authentication path using bcrypt + JWT
- Data flow from CSV upload to client-side parsing/visualization
- Data flow from dashboard analysis to backend persistence and AI recommendation generation
- Data flow from backend to Facebook comments/sentiment analysis

#### Summary

This repo is best understood as a monolithic full-stack dashboard:
- The frontend is responsible for interaction and visualization.
- The backend is responsible for security, orchestration, and integrations.
- SQLite stores user and analysis history locally.
- External APIs provide social sentiment and AI-generated marketing recommendations.

The architectural center is the backend API layer, which connects the browser-facing dashboard to storage and third-party intelligence services.

Main entry points: [`script.js`](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/script.js) (Client app), [`server.js`](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/server.js) (Server app), [`database.js`](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/database.js) (DB access), [`index.html`](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/index.html) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Browser client"
  index_html["Dashboard shell<br/>html entry<br/>[index.html]"]
  style_css["Styles<br/>css theme<br/>[style.css]"]
  script_js["Client app<br/>browser logic<br/>[script.js]"]
end

subgraph "Node backend"
  server_js["Server app<br/>express server<br/>[server.js]"]
  auth_gate{{"Auth guard<br/>jwt+bcrypt"}}
  analysis_api["Analysis API<br/>dashboard orchestration"]
  gemini_client["Gemini client<br/>ai integration"]
  facebook_client["Facebook client<br/>social integration"]
end

subgraph "Persistence"
  database_js["DB access<br/>sqlite adapter<br/>[database.js]"]
  sqlite_store[("SQLite store<br/>local database")]
  users_data[("Users<br/>account records")]
  history_data[("History<br/>analysis records")]
end

subgraph "External services"
  gemini_api(("Google Gemini<br/>external AI"))
  facebook_api(("Graph API<br/>external social api"))
end

index_html -->|"loads"| script_js
index_html -->|"styles"| style_css
script_js -->|"requests"| server_js
server_js -->|"verifies"| auth_gate
server_js -->|"routes"| analysis_api
analysis_api -->|"persists"| database_js
database_js -->|"reads/writes"| sqlite_store
sqlite_store -->|"contains"| users_data
sqlite_store -->|"contains"| history_data
analysis_api -->|"calls"| gemini_client
gemini_client -->|"invokes"| gemini_api
analysis_api -->|"calls"| facebook_client
facebook_client -->|"invokes"| facebook_api
auth_gate -->|"checks"| database_js
script_js -->|"visualizes"| analysis_api

click index_html "https://github.com/ctrlne/cocopan-data-sales/blob/main/index.html"
click style_css "https://github.com/ctrlne/cocopan-data-sales/blob/main/style.css"
click script_js "https://github.com/ctrlne/cocopan-data-sales/blob/main/script.js"
click server_js "https://github.com/ctrlne/cocopan-data-sales/blob/main/server.js"
click database_js "https://github.com/ctrlne/cocopan-data-sales/blob/main/database.js"

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 index_html,style_css,script_js toneBlue
class server_js,auth_gate,analysis_api,gemini_client,facebook_client toneAmber
class database_js,sqlite_store,users_data,history_data toneMint
class gemini_api,facebook_api toneRose
```

## Components

### Browser client

User-facing dashboard, interaction, and visualization

- [Dashboard shell](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/index.html): html entry · Main document that boots the app UI · `index.html`
- [Styles](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/style.css): css theme · App styling for the dashboard · `style.css`
- [Client app](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/script.js): browser logic · UI interactions, CSV handling, charts, and API calls · `script.js`

### Node backend

Express server, auth, orchestration, and API integration

- [Server app](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/server.js): express server · HTTP server, static file serving, and backend endpoints · `server.js`
- **Auth guard**: jwt+bcrypt · Login, password verification, and protected requests
- **Analysis API**: dashboard orchestration · Coordinates uploads, history, recommendations, and sentiment workflows
- **Gemini client**: ai integration · Server-side calls for recommendations and analysis help
- **Facebook client**: social integration · Fetches page comments for sentiment workflows

### Persistence

Local SQLite storage and data access

- [DB access](https://github.com/ctrlne/cocopan-data-sales/blob/HEAD/database.js): sqlite adapter · Encapsulates schema and queries for local storage · `database.js`
- **SQLite store**: local database · Embedded persistence for users and analysis history
- **Users**: account records · Stored identities and credentials metadata
- **History**: analysis records · Saved analysis sessions and results

### External services

Third-party AI and social APIs

- **Google Gemini**: external AI · Third-party generative AI service
- **Graph API**: external social api · Third-party Facebook comments source

## Connections

- Dashboard shell → Client app: loads · Browser bootstraps the client logic
- Dashboard shell → Styles: styles · Dashboard styling is applied in the browser
- Client app → Server app: requests · Client sends login, history, save, and AI requests
- Server app → Auth guard: verifies · Protects privileged endpoints with auth checks
- Server app → Analysis API: routes · Dispatches dashboard workflows and API handlers
- Analysis API → DB access: persists · Stores and retrieves application data through the DB layer
- DB access → SQLite store: reads/writes · Executes SQLite operations
- SQLite store → Users: contains · User account records
- SQLite store → History: contains · Saved analysis history
- Analysis API → Gemini client: calls · Builds AI requests for recommendations and analysis
- Gemini client → Google Gemini: invokes · Server-side request to Google Gemini
- Analysis API → Facebook client: calls · Fetches social comments for sentiment workflows
- Facebook client → Graph API: invokes · Server-side request to Facebook Graph API
- Auth guard → DB access: checks · Verifies users against stored account data
- Client app → Analysis API: visualizes · Renders charts, tables, and analysis results
