# victorialslocum/basic-chat-app architecture

> Architecture diagram of the GitHub repository victorialslocum/basic-chat-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victorialslocum/basic-chat-app
- Repository: https://github.com/victorialslocum/basic-chat-app

## Overview

##### Project Type & Purpose
- This is a modern, full-stack “chat + semantic search + file management” application template.
- Frontend: Next.js (React + TypeScript + Tailwind CSS)
- Backend: FastAPI (Python)
- Database: Weaviate vector database
- External AI service: OpenAI API

##### File Structure
Top-level folders
- backend/ – FastAPI code, Pydantic schemas, Weaviate config, service layer, upload storage
- frontend/ – Next.js App Router pages, reusable UI/chat/search/upload components, API client lib, type definitions
Key patterns
- Frontend using App Router conventions: each feature (chat, search, upload, object/[id]) as a page subtree + shared components under app/components

##### Extract Insights from README
- Core features (intelligent chat, semantic search, file upload) are encapsulated in dedicated service modules
- Customization points clearly marked in both backend and frontend
- Tech stack and external dependencies (Weaviate, OpenAI) explicitly listed

##### Main Components & Their Interactions
a. Frontend (browser)
– Next.js pages (chat UI, search UI, upload UI, object detail)
– UI components call API endpoints via app/lib/api.ts
b. Backend API (FastAPI)
– api.py defines /api/chat, /api/search, /api/upload, /api/data, /uploads static route
– Delegates requests to chat_service, data_service, upload_service
c. Service Layer
– chat_service: orchestrates OpenAI calls + merges vector search context
– data_service: queries Weaviate, paginates results, maps to Pydantic SearchResult
– upload_service: stores files in uploads/, invokes vectorization & indexing
d. Database & Vector Engine
– Weaviate: hosts multiple collections (chats, messages, custom data)
– Configured via backend/config/database.py, created on startup if missing
e. External AI Service
– OpenAI: generates chat responses and embeddings (if not using Weaviate’s text2vec)

##### Architectural Patterns & Design Principles
- Layered Architecture: Presentation (Next.js) → API (FastAPI routes) → Business Logic (services) → Data Access (Weaviate)
- Micro-layering in backend promotes easy customization of only schema or collection names without touching chat/upload logic
- Frontend componentization (atomic UI + feature modules) ensures reusability

##### Essential Elements to Capture
- Frontend App Router structure and API client
- FastAPI router definitions in api.py
- Service modules and their dependencies (highlight which require customization)
- Weaviate collections and generative config
- OpenAI integration paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        ChatPage["Chat Page"]:::frontend
        SearchPage["Search Page"]:::frontend
        UploadPage["Upload Page"]:::frontend
        ObjectDetailPage["Object Detail Page"]:::frontend
        Navigation["Navigation"]:::frontend
        subgraph "Chat Components"
            direction TB
            ChatContainer["ChatContainer"]:::frontend
            ChatInput["ChatInput"]:::frontend
            ChatSidebar["ChatSidebar"]:::frontend
            MessageBubble["MessageBubble"]:::frontend
            PaginatedSources["PaginatedSources"]:::frontend
        end
        subgraph "Search Components"
            direction TB
            SearchBar["SearchBar"]:::frontend
            SearchResults["SearchResults"]:::frontend
            SearchResultCard["SearchResultCard"]:::frontend
        end
        subgraph "Upload Components"
            direction TB
            FileUpload["FileUpload"]:::frontend
            UploadProgress["UploadProgress"]:::frontend
        end
        subgraph "UI Primitives"
            direction TB
            Button["Button"]:::frontend
            Card["Card"]:::frontend
            Input["Input"]:::frontend
        end
        Layout["App Layout"]:::frontend
        GlobalsCSS["globals.css"]:::frontend
        TailwindConfig["tailwind.config.ts"]:::frontend
        APIClient["API Client (app/lib/api.ts)"]:::frontend
        Types["Type Definitions (app/lib/types.ts)"]:::frontend

        ChatPage -->|uses| Navigation
        SearchPage -->|uses| Navigation
        UploadPage -->|uses| Navigation
        ObjectDetailPage -->|uses| Navigation

        ChatPage -->|renders| ChatContainer
        ChatContainer --> ChatInput
        ChatContainer --> ChatSidebar
        ChatSidebar --> MessageBubble
        ChatContainer --> PaginatedSources

        SearchPage -->|renders| SearchBar
        SearchPage --> SearchResults
        SearchResults --> SearchResultCard

        UploadPage -->|renders| FileUpload
        UploadPage --> UploadProgress

        ChatPage --> APIClient
        SearchPage --> APIClient
        UploadPage --> APIClient
        ObjectDetailPage --> APIClient

        Layout --> ChatPage
        Layout --> SearchPage
        Layout --> UploadPage
        Layout --> ObjectDetailPage
        Layout --> Navigation
        Layout --> GlobalsCSS
        Layout --> TailwindConfig

        APIClient -->|"HTTP POST/GET"| backendAPI
    end

    %% Backend Layer
    subgraph "Backend" 
        direction TB
        backendAPI["FastAPI Routes (api.py)"]:::backend
        subgraph "Service Layer"
            direction TB
            ChatService["Chat Service"]:::backend
            DataService["Data Service"]:::backend
            UploadService["Upload Service"]:::backend
        end
        ModelsSchemas["Models & Schemas (schemas.py)"]:::backend
        DBConfig["Weaviate Config (database.py)"]:::backend
        EnvExample[".env.example"]:::backend
        Requirements["requirements.txt"]:::backend
        UploadStorage["Uploads Storage"]:::backend

        backendAPI -->|delegates to| ChatService
        backendAPI -->|delegates to| DataService
        backendAPI -->|delegates to| UploadService

        ChatService -->|calls| OpenAI
        ChatService -->|queries| WeaviateDB
        DataService -->|queries| WeaviateDB
        UploadService -->|stores files| UploadStorage
        UploadService -->|indexes| WeaviateDB

        DBConfig --> WeaviateDB
        ModelsSchemas --> ChatService
        ModelsSchemas --> DataService
        ModelsSchemas --> UploadService
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    WeaviateDB[(Weaviate)]:::database

    %% Connections
    OpenAI -.->|Embedding & Chat| ChatService
    OpenAI -.->|Generative Config| WeaviateDB

    classDef frontend fill:#D0E8FF,stroke:#0094FF,color:#000
    classDef backend fill:#E6FFE6,stroke:#00AA00,color:#000
    classDef database fill:#FFF0C1,stroke:#FFAA00,color:#000
    classDef external fill:#F0F0F0,stroke:#888,color:#000

    %% Click Events
    click ChatPage "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/chat/page.tsx"
    click SearchPage "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/search/page.tsx"
    click UploadPage "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/upload/page.tsx"
    click ObjectDetailPage "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/object/[id]/page.tsx"
    click Navigation "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/Navigation.tsx"
    click ChatContainer "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/chat/ChatContainer.tsx"
    click ChatInput "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/chat/ChatInput.tsx"
    click ChatSidebar "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/chat/ChatSidebar.tsx"
    click MessageBubble "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/chat/MessageBubble.tsx"
    click PaginatedSources "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/chat/PaginatedSources.tsx"
    click SearchBar "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/search/SearchBar.tsx"
    click SearchResults "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/search/SearchResults.tsx"
    click SearchResultCard "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/search/SearchResultCard.tsx"
    click FileUpload "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/upload/FileUpload.tsx"
    click UploadProgress "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/upload/UploadProgress.tsx"
    click Button "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/ui/Button.tsx"
    click Card "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/ui/Card.tsx"
    click Input "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/components/ui/Input.tsx"
    click Layout "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/layout.tsx"
    click GlobalsCSS "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/globals.css"
    click TailwindConfig "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/tailwind.config.ts"
    click APIClient "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/lib/api.ts"
    click Types "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/app/lib/types.ts"
    click backendAPI "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/api.py"
    click ChatService "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/services/chat_service.py"
    click DataService "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/services/data_service.py"
    click UploadService "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/services/upload_service.py"
    click ModelsSchemas "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/models/schemas.py"
    click DBConfig "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/config/database.py"
    click EnvExample "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/.env.example"
    click Requirements "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/requirements.txt"
    click README "https://github.com/victorialslocum/basic-chat-app/blob/master/README.md"
    click FrontendREADME "https://github.com/victorialslocum/basic-chat-app/blob/master/frontend/README.md"
    click BackendREADME "https://github.com/victorialslocum/basic-chat-app/blob/master/backend/README.md"
    click PromptTemplate "https://github.com/victorialslocum/basic-chat-app/blob/master/prompt.txt"
```
