Skip to main content

System Architecture Explained

Table of Contents​

  1. Technology Stack Overview
  2. System Architecture Design
  3. Project File Structure
  4. API Interface Design
  5. Application Page Overview

Technology Stack Overview​

The term "technology stack" sounds impressive, but it's essentially the complete set of "tool combinations" we've chosen to build this project. Just like building a house requires cranes, mixers, and scaffolding, developing software also needs different tools to perform their respective roles.

What Are Frontend and Backend?​

Before introducing specific tools, let's understand the most important concept: Frontend and Backend.

You can think of our entire application as a high-end restaurant:

  • Frontend: Everything you can directly see and interact with. It's the restaurant's lobby, menu, tables and chairs, and the waiters serving you. In our application, all pages, buttons, and charts you see in the browser belong to the frontend. Its main responsibilities are presenting information and interacting with you.

  • Backend: The "heart" that you can't see but supports the restaurant's operation—the kitchen. It handles orders (your requests), cooks dishes (data analysis and AI computation), and manages inventory (databases). In our application, the backend is responsible for handling complex business logic, calling Gemini AI models, communicating with external services like Google Sheets, and returning final results to the frontend.

Frontend and backend communicate through a strict "ordering system" (i.e., API), ensuring that waiters (frontend) can accurately convey your needs to the kitchen (backend) and perfectly present the cooked dishes (results) to you.

Our project's frontend and backend code are completely separated, which is a modern development pattern called "frontend-backend separation." Its benefit is that the restaurant lobby's decoration and kitchen equipment upgrades can proceed independently without interference, greatly improving development and maintenance efficiency.

React: Building User Interfaces Like Building with LEGO​

  • What is it? React is a frontend "framework" developed and open-sourced by Facebook (now Meta), currently the world's most popular.
  • What does it do? Its core idea is "componentization." You can think of the entire webpage as a huge LEGO model, and this model is built by independent, reusable "LEGO bricks." In our project, a button, a dropdown menu, a data table, or even an entire slide preview is an independent "component."
  • Why use it?
    • Efficient Development: We can first carefully design various basic "bricks" (components), then quickly assemble them like LEGO wherever needed, without starting from scratch every time.
    • Easy Maintenance: If we find a button doesn't look good, we only need to modify the "button component" itself, and all places using it will automatically update without affecting other parts. Pages like AudienceSignalPage and GeoAnalysisPage can be so similar and unified precisely because of the high reusability of componentization.
    • Powerful Ecosystem: As the most popular framework, React has extremely rich community and third-party library support. We can easily find various high-quality "LEGO parts" (such as chart libraries, UI libraries) to enrich our application.

Vite: The "Engine" That Makes Our Development and Browsing Fly​

  • What is it? Vite (pronounced /vit/, meaning "fast" in French) is the frontend build tool and development server chosen for our project.
  • What does it do?
    1. During Development: When developers write code, Vite acts like an ultra-fast "simultaneous interpreter," instantly reflecting changes in the browser the moment code is saved, with almost no waiting. This greatly improves development experience and efficiency.
    2. Before Deployment: When we need to deploy the project to a server, Vite plays the role of a "packaging compressor." It optimizes, compresses, and packages the hundreds or thousands of frontend code files we write (HTML, CSS, TypeScript), ultimately generating several highly optimized static files, allowing users to load and access them at the fastest speed in the browser.
  • Why use it? For one word—speed. Compared to traditional build tools, Vite has orders of magnitude improvements in startup speed and hot reload speed during development, making it the current "rising star" in frontend development.

Node.js: The "Brain" That Makes Our Server Respond to Requests​

  • What is it? Node.js is an "environment" that allows the JavaScript language to run directly on servers, independent of browsers.
  • What does it do? In our project, the entire backend service (the restaurant's kitchen) is driven by Node.js. It's responsible for receiving requests from the frontend (taking orders), executing core logic like geminiService.ts (cooking), and returning results to the frontend.
  • Why use it?
    • Unified Language: Using Node.js means both our frontend and backend use the same main programming language—JavaScript (and TypeScript). This greatly reduces learning costs and mental burden for independent developers, allowing them to focus more on business logic itself without frequently switching between two completely different languages.
    • High Performance: Node.js is particularly good at handling large numbers of concurrent network requests (simultaneously serving many tables of customers), making it very suitable for building API services like ours that frequently interact with the frontend.

TypeScript: The "Navigator" That Adds "Intelligent Hints" to Code​

  • What is it? TypeScript is developed and open-sourced by Microsoft and can be seen as a "superset" of JavaScript (can be understood as a "professional enhanced version").
  • What does it do? Its core function is adding a static type system to JavaScript. This sounds complex, but you can understand it as an extremely strict and intelligent "syntax checker and code navigator."
    • Early Error Detection: In traditional JavaScript, many errors (such as treating a number as text) only surface when the program actually runs. TypeScript, while we write code, acts like a strict co-pilot, checking our code in real-time. If it finds type mismatches, it immediately highlights errors with red lines. This greatly reduces the number of production bugs.
    • Intelligent Code Hints: Because TypeScript knows the "type" of every variable and function, when we write code, the editor can provide extremely precise intelligent hints and auto-completion. This not only improves development efficiency but also makes reading and understanding others' code exceptionally easy.
  • Why use it? For a project that needs long-term maintenance and multi-person collaboration, the improvements in code robustness and maintainability brought by TypeScript are invaluable. It's like establishing a "living documentation" for project code, a key foundation ensuring we can successfully collaborate on development in the future.

Design Languages: From Semi Design to Ant Design​

  • What are they? Semi Design (by ByteDance) and Ant Design (by Ant Group) are two frontend UI component libraries used in our project.
  • What do they do? They provide us with a large number of pre-designed and developed, high-quality UI components (the "LEGO bricks" we mentioned earlier), such as buttons, forms, tables, popups, menus, etc. We don't need to draw buttons and write styles from scratch; we can directly use these ready-made, beautifully designed and powerful components.
  • Project Status:
    • According to project rules, the current three core features (Market Opportunity Analysis, Audience Signal Analysis, Persona Slide) are built using Semi Design.
    • For gradual unification and modernization of the technology stack, all newly developed pages in the future will be recommended to use Ant Design.

This technology stack selection balances development efficiency, code robustness, future scalability, and seamless integration with the Google ecosystem. It's the result of careful consideration and continuous refinement during project development, and it's the solid foundation that enables our project to run stably and efficiently.

System Architecture Design​

If the "technology stack" from the previous section is the "tools and materials" we use to build a house, then "system architecture" is the "architectural blueprint" we've planned. It describes how various functional modules are organized and connected to collectively support the entire application.

Macro Architecture Diagram: Understanding Data Flow at a Glance​

To give you an intuitive overall understanding of the project, let's first look at a complete data flow diagram from user operations to result generation:

sequenceDiagram
    participant U as User
    participant FE as Frontend (Browser/React)
    participant BE as Backend (Node.js Server)
    participant GA as Google Apps Script
    participant GS as Google Gemini API
    participant GSuite as Google Workspace (Sheets/Slides)

    U->>FE: 1. Access webpage, login with Google account
    FE->>BE: 2. Initiate Google OAuth authentication request
    BE-->>FE: 3. Return authentication Token
    FE-->>U: 4. Login successful, display feature homepage

    U->>FE: 5. Fill out form on page, upload data file
    FE->>BE: 6. Send data and Prompt instructions to backend API<br>(e.g., /api/gemini/generate)
    
    subgraph Backend Processing Core Logic
        BE->>GS: 7. (Core) Call Gemini API for AI analysis<br>Includes comprehensive retry and error handling mechanisms
        GS-->>BE: 8. Return analysis results (JSON text)
    end

    BE-->>FE: 9. Return AI analysis results to frontend
    FE->>U: 10. (Some features) Display results on page<br>Such as charts, tables

    subgraph (Optional) Google Workspace Integration
        FE->>BE: 11. (Some features) Initiate slide generation/logging request
        BE->>GA: 12. Call Apps Script API<br>Pass data and user identity
        GA->>GSuite: 13. In Google Slides/Sheets<br>Create slides, insert images, write logs
        GSuite-->>GA: 14. Return operation results
        GA-->>BE: 15. Return operation results
        BE-->>FE: 16. Return final results
    end
    
    FE->>U: 17. Display final results, provide download/link

This diagram clearly shows several core characteristics of our system:

  1. Frontend-Backend Separation: The user's browser (frontend) and our server (backend) are two independent parts, communicating clearly through APIs.
  2. Backend as "Intelligent Hub": All core AI computation and integration with Google services are handled uniformly by the backend. This ensures security (API keys are not exposed in the frontend) and robustness (the backend implements comprehensive retry and logging).
  3. Deep Google Ecosystem Integration: The project is not just an independent website; it deeply integrates Google authentication, Gemini AI, Google Sheets, and Google Slides, forming a powerful, seamlessly connected Google Workspace solution.

Project File Structure​

A clearly structured file directory is like a good treasure map, allowing developers to quickly locate the code they want to find. Our project follows industry best practices, organizing code for different functions into designated locations.

/
├── server/                 # Store all "backend" code (restaurant kitchen)
│   ├── index.ts            # Backend service "master switch," defines all API interfaces
│   ├── geminiService.ts    # Encapsulates core logic for calling Gemini API (most important chef)
│   └── ...                 # Other auxiliary tools and configurations
│
├── src/                    # Store all "frontend" code (restaurant lobby)
│   ├── pages/              # Store application "pages," each file corresponds to a main page you can see
│   │   ├── GeoAnalysisPage.tsx     # "Market Opportunity Analysis" page
│   │   ├── AudienceSignalPage.tsx  # "Audience Signal Analysis" page
│   │   └── PersonaSlidePage.tsx    # "Persona Slide" page
│   │
│   ├── components/         # Store reusable "UI bricks" (buttons, tables, charts, etc.)
│   │
│   ├── features/           # Store "business logic" for three core features
│   │   ├── geo-analysis/
│   │   ├── audience-signal/
│   │   └── persona-slide/
│   │
│   ├── hooks/              # Store custom "logic hooks" for encapsulating complex state management
│   │   └── useGeoAnalysis.ts # Core logic for "Market Opportunity Analysis" page is encapsulated here
│   │
│   ├── services/           # Store code for communicating with backend APIs or external services
│   ├── routes/             # Defines the entire application's "navigation map," i.e., page routing
│   ├── contexts/           # Provides "shared space" for globally shared data (such as user info, language config)
│   ├── i18n/               # Store multilingual internationalization related files
│   └── ...                 # Other frontend related files
│
├── docs/                   # Place to store all project documentation
│   └── project-white-paper/  # This white paper you're reading
│
├── public/                 # Store static resources (images, fonts, etc., no packaging needed)
│
└── package.json            # Project's "ID card," records all third-party libraries the project depends on

After understanding this structure, even newly joined developers can quickly find the code locations they need to modify or read based on requirements. For example:

  • Want to modify a button style on the "Market Opportunity Analysis" page? Should go to src/pages/GeoAnalysisPage.tsx or src/components/ to find the corresponding component.
  • Want to adjust a parameter for calling Gemini API? Should go to server/geminiService.ts.
  • Want to add a new analysis feature page? Need to create a new page file in src/pages/, configure routing in src/routes/, and write new business logic in src/features/.

API Interface Design​

Frontend and backend communicate through API (Application Programming Interface). You can understand it as the "standard dialogue format" for passing orders between restaurant waiters (frontend) and the kitchen (backend).

Our backend service (server/index.ts) defines a series of API "endpoints," each corresponding to a specific function. The frontend accesses these endpoints through network requests and passes necessary parameters.

Core API Endpoints​

The following are the most core API endpoints in our project:

1. Text Generation API​

  • POST /api/gemini/generate
    • Function: Executes core text analysis and content generation.
    • Frontend needs to pass: Gemini model name to use, carefully constructed Prompt (instructions), and data to analyze.
    • Backend returns: Text results generated by Gemini (usually structured JSON).

2. Image Generation API​

  • POST /api/gemini/generate-image
    • Function: Executes image generation tasks.
    • Frontend needs to pass: Image generation model name to use, Prompt describing the image.
    • Backend returns: Base64-encoded data of the generated image.

3. Google Slides Integration API​

  • POST /api/slides/insert-image
    • Function: Inserts an image into a specified position in Google Slides.
    • Frontend needs to pass: Google Slides ID, image data, and the "marker" for where the image should be inserted.
    • Backend returns: Apps Script execution results.

4. Audit Log API​

  • POST /api/audit-logs/*
    • Function: Records various user behavior logs (such as login, feature usage, result export, etc.).
    • Frontend needs to pass: User identity information, operation type, and related context data.
    • Backend returns: Confirmation of successful recording.

This carefully designed API interface set forms a solid bridge for frontend-backend collaboration, ensuring data and instructions can flow accurately and efficiently within the system.

Application Page Overview​

The system includes the following main pages, each with its specific functions and purposes:

1. Login Page (/login)​

  • Function: Users log in to the system using Google accounts
  • Main Components: Google OAuth login button
  • Access Permission: Public access, logged-in users automatically redirected to homepage

2. Dashboard Page (/)​

  • Function: System homepage, displays project welcome information and core feature entry points
  • Main Components:
    • Feature cards (Market Opportunity Analysis, Audience Signal Analysis, Persona Slide)
    • Quick links
    • Workflow detector (supports pasting Google Sheet links to automatically identify workflow type)
  • Access Permission: Requires login

3. Market Opportunity Analysis Page (/geo-analysis)​

  • Function: Analyze market data across different countries/regions, identify market opportunities
  • Main Components:
    • Data upload form (supports Excel file upload and Google Sheet links)
    • Analysis parameter configuration (number of countries, prompt templates, etc.)
    • Progress display component
    • Result display (bubble charts, slide previews)
  • Access Permission: Requires login
  • Detailed Documentation: Market Opportunity Analysis Deep Dive Guide

4. Audience Signal Analysis Page (/audience-signal)​

  • Function: Deeply analyze user search behavior data, perform intent categorization and topic clustering
  • Main Components:
    • Data upload form
    • Analysis parameter configuration
    • Progress display component
    • Result display (data tables, slide previews)
  • Access Permission: Requires login
  • Detailed Documentation: Audience Signal Analysis Deep Dive Guide

5. Persona Slide Page (/persona-slide)​

  • Function: Automatically generate beautiful user persona slide reports
  • Main Components:
    • Data upload form
    • Analysis parameter configuration
    • Progress display component (includes image generation progress)
    • Result display (multiple user persona slide previews)
  • Access Permission: Requires login
  • Detailed Documentation: Persona Slide Deep Dive Guide

6. Workflow Results Page (/workflow/:workflowId)​

  • Function: Unified results display page, supports result display for all three workflow types
  • Main Components:
    • Result visualization components (dynamically rendered based on workflow type)
    • Export functions (ZIP, PPTX, images, etc.)
    • Edit functions (some content editable)
  • Access Permission: Requires login
  • Features: Supports loading historical results from browser local storage

7. Workflow Conversation Page (/c/:workflowId)​

  • Function: Workflow execution and result display based on conversational interface
  • Main Components:
    • Conversation interface
    • File upload and Google Sheet link processing
    • Workflow type automatic identification
  • Access Permission: Requires login
  • /slide-craft: SlideCraft homepage
  • /slide-craft/workflow/create: Create workflow
  • /slide-craft/workflow/result/:workflowId: Workflow results page (legacy version, redirected to unified results page)

Summary​

This section detailed the project's system architecture, including:

  1. Technology Stack Overview: Core technology selections such as frontend, backend, build tools, UI component libraries
  2. System Architecture Design: Frontend-backend separation architecture, data flow diagrams, Google ecosystem integration
  3. Project File Structure: Code organization methods, directory structure explanations
  4. API Interface Design: Core API endpoints and their function descriptions
  5. Application Page Overview: Function and component descriptions for all main pages

These architectural designs ensure the system can run stably and efficiently, providing a solid foundation for future expansion and maintenance.

Related Documentation: