# tecnhotron/singularity architecture

> Architecture diagram of the GitHub repository tecnhotron/singularity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tecnhotron/singularity
- Repository: https://github.com/tecnhotron/singularity

## Overview

##### Project type and purpose
- This is a full-stack chat application (“Singularity”) with:
- A static frontend (HTML/CSS/JS)
- A Flask-based REST API backend
- Firebase Firestore as the data store
- Integration with the Gemini AI API for generating chat responses

##### File structure
- Top-level files
- Dockerfile: containerization of the service
- server.py (or app.py in README): main Flask application
- requirements.txt: Python dependencies
- Static assets
- index.html, login.html, register.html: client entry points
- css/: styling
- js/: client logic modules (login, register, chat script, firebase-config, document-tool, image-tool, utilities)
- External config
- firebase-key.json: service account credentials for Firestore
- firebase-config.js: client Firebase SDK config
- README.md: describes backend setup, endpoints, and features

##### README for insights
- Lists REST endpoints for chats, messages, settings, gems
- Describes use of Firestore, Gemini API, and Prompt Gems
- Notes custom chat-creation behavior in frontend

##### Main components
a. Frontend (Browser)
- HTML pages + CSS
- JS modules: authentication, chat UI, document/image generation, API key management
- Firebase Web SDK for client-side config (optional)
b. Backend (Flask App)
- API layer with endpoints under /api/*
- Request handlers for chats, messages, settings, gems, new-chat
- Integration module for calling Gemini API
- Firestore client library for data persistence
c. Database
- Firebase Firestore: collections for users, chats, messages, gems, settings
d. External Service
- Gemini AI API (Google AI Studio) for AI-powered responses

##### Relationships and interactions
- User interacts with the frontend (login, register, chat UI)
- Frontend sends HTTP requests (AJAX/fetch) to Flask API
- Flask API:
- Reads/writes chat records in Firestore
- Reads/writes user settings and prompt gems
- Calls Gemini API to generate AI responses
- Returns JSON payloads to the client
- Optionally, client may use Firebase SDK for real-time updates (if applicable)

##### Architectural patterns and design principles
- Client–server separation: UI logic in JavaScript, business logic in Flask
- RESTful API design for modular, stateless endpoints
- Layered architecture: Presentation (frontend), Application (Flask), Data (Firestore), External (Gemini)
- Extensibility points: Prompt Gems endpoint, document/image tool modules

##### Relevant technologies/frameworks
- Frontend: Vanilla JS, Firebase Web SDK, HTML5, CSS3
- Backend: Python 3.8+, Flask, firebase-admin SDK, requests (for Gemini)
- Deployment: Docker (Dockerfile)
- Database: Google Firestore
- AI Service: Google Gemini API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser (Frontend)" 
        style Browser fill:#D0E8FF,stroke:#0062A3,stroke-width:2px
        HTML[Index, Login, Register Pages]:::frontend
        CSS[CSS Styles]:::frontend
        JS[JS Modules]:::frontend
    end

    HTML -->|"renders"| CSS
    HTML -->|"loads"| JS

    click HTML "https://github.com/tecnhotron/singularity/blob/main/index.html"
    click HTML "https://github.com/tecnhotron/singularity/blob/main/login.html"
    click HTML "https://github.com/tecnhotron/singularity/blob/main/register.html"
    click CSS "https://github.com/tecnhotron/singularity/blob/main/css/styles.css"
    click CSS "https://github.com/tecnhotron/singularity/blob/main/css/document-styles.css"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/login.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/register.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/script.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/firebase-config.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/document-generator.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/document-tool.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/document-utils.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/image-generator.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/image-tool.js"
    click JS "https://github.com/tecnhotron/singularity/blob/main/js/image-utils.js"

    %% Backend Layer
    subgraph "Docker Container" 
        style Docker fill:#E0FFE0,stroke:#1A731A,stroke-width:2px
        subgraph "Flask API" 
            style Flask fill:#E0FFE0,stroke:#1A731A,stroke-width:1px
            Server["server.py\n(REST API Endpoints)"]:::backend
            Requirements["requirements.txt"]:::backend
            Dockerfile["Dockerfile"]:::backend
            README["README.md"]:::backend
        end
    end

    click Server "https://github.com/tecnhotron/singularity/blob/main/server.py"
    click Requirements "https://github.com/tecnhotron/singularity/blob/main/requirements.txt"
    click Dockerfile "https://github.com/tecnhotron/singularity/tree/main/Dockerfile"
    click README "https://github.com/tecnhotron/singularity/blob/main/README.md"

    %% Data Layer
    subgraph "Database (Firestore)" 
        style DB fill:#FFE8B0,stroke:#B36F00,stroke-width:2px
        Collections["Collections:\nusers, chats, messages,\ngems, settings"]:::data
    end

    %% External Service
    Gemini["Gemini AI API"]:::external

    %% Interactions
    HTML -->|"AJAX/Fetch\nHTTP GET/POST"| Server
    JS -->|"AJAX/Fetch\nHTTP Requests"| Server
    Server -->|"CRUD Operations"| Collections
    Server -->|"AI Request"| Gemini
    Server -->|"JSON Response"| HTML

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0062A3,stroke-width:1px
    classDef backend fill:#E0FFE0,stroke:#1A731A,stroke-width:1px
    classDef data fill:#FFE8B0,stroke:#B36F00,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px
```
