How ctrlne/cocopan-data-sales works
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 Client app · server.js Server app · database.js DB access · index.html Dashboard shell
Components 14
Browser client
User-facing dashboard, interaction, and visualization
- Dashboard shell · Main document that boots the app UI
index.html - Styles · App styling for the dashboard
style.css - Client app · UI interactions, CSV handling, charts, and API calls
script.js
Node backend
Express server, auth, orchestration, and API integration
- Server app · HTTP server, static file serving, and backend endpoints
server.js - Auth guard · Login, password verification, and protected requests
- Analysis API · Coordinates uploads, history, recommendations, and sentiment workflows
- Gemini client · Server-side calls for recommendations and analysis help
- Facebook client · Fetches page comments for sentiment workflows
Persistence
Local SQLite storage and data access
- DB access · Encapsulates schema and queries for local storage
database.js - SQLite store · Embedded persistence for users and analysis history
- Users · Stored identities and credentials metadata
- History · Saved analysis sessions and results
External services
Third-party AI and social APIs
- Google Gemini · Third-party generative AI service
- Graph API · Third-party Facebook comments source
Connections 15
- 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