# yuconnorl/psychedelics-db architecture

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

- Interactive diagram: https://gitdiagram.com/yuconnorl/psychedelics-db
- Repository: https://github.com/yuconnorl/psychedelics-db

## Overview

##### Main Components
- Client/Frontend – Built on Next.js (see the “app” directory with pages such as “/database”, “/research”, and “/about”) and a variety of reusable UI components in “src/components” and “src/components/ui”.
- Backend API Endpoints – There are two major sets of API routes:
○ Under “app/api”: Legacy endpoints (for example, for OG research data and paper endpoints).
○ Under “app/apiv2”: Newer endpoints handling advanced functions (embedding, research paper extraction, translation, summarization, vector search) which interface with LLM services (e.g., GPT-4/Gemini) and vector databases.
- Content Management – Payload CMS configuration (observable via “src/payload.config.ts” and related files) that provides the data source for the research articles and educational materials.
- External Services & Integrations – The project integrates a vector database for retrieval-augmented generation (PsycheLens) and uses Algolia (client and related components) for search functionalities.
- Utilities and Configuration – Additional support files such as “src/config”, “src/utilities”, and the server entry points (“src/server.ts”, “src/server.default.ts”) that glue the system together.

##### Relationships and Data Flow
- Browser/Client interacts with the Next.js frontend. The client fetches pages and interacts with API endpoints.
- Frontend Request Flow:
○ Navigation routes (database, research, about) are rendered by Next.js.
- API Layer:
○ Requests from the frontend are routed to the “app/api” and “app/apiv2” endpoints.
○ These endpoints process the requests (data extraction, summarization, embedding, etc.), interfacing with external LLM services and vector databases.
- Payload CMS:
○ The CMS acts as a stored content repository for research papers and educational content.
○ The API queries Payload CMS to fetch/update content as needed.
- External Integrations:
○ APIs for LLM services and vector search are called from the “apiv2” endpoints.
○ Algolia client in “src/utilities” and “src/components/algolia” coordinates search functionality that feeds into the frontend.

##### Architectural Patterns and Design Principles
- Separation of Concerns – Clear division between frontend rendering (React components, Next.js pages) and backend API logic.
- API Versioning – The “apiv2” folder indicates an evolution of endpoints, hinting at a deliberate design for backward compatibility and incremental improvements.
- Modular & Reusable Components – Extensive use of component-based architecture for UI (in “src/components”) and helper utilities.
- Client–Server Communication – Utilizes API routes to connect the presentation layer to the data and processing layers, often via RESTful or similar protocols.
- Integration of External Services – Both CMS (Payload) and external LLM/vector search services are loosely coupled with designated endpoints handling communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        U["User Browser"]:::client
        FE["Next.js Frontend"]:::frontend
        UI["Reusable UI Components"]:::frontend
    end

    %% API Gateway Layer
    subgraph "API Gateway"
        direction TB
        API_Legacy["Legacy API Endpoints"]:::api
        API_V2["APIV2 Endpoints"]:::api
    end

    %% Content Management
    subgraph "Content Management"
        direction TB
        CMS["Payload CMS"]:::cms
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM & Vector Services"]:::external
        ALG["Algolia"]:::external
    end

    %% Utilities and Configuration Modules
    subgraph "Utilities & Config Modules"
        direction TB
        UTIL["Utilities & Config Modules"]:::utility
    end

    %% Connections
    U -->|"requests"| FE
    FE -->|"renders"| UI
    FE -->|"fetchesData"| API_Legacy
    FE -->|"fetchesData"| API_V2
    API_Legacy -->|"contentQuery"| CMS
    API_V2 -->|"contentQuery"| CMS
    API_V2 -->|"callsLLM"| LLM
    UI -->|"triggersSearch"| ALG
    UTIL ---|"supports"| FE
    UTIL ---|"configures"| API_V2

    %% Click Events
    click FE "https://github.com/yuconnorl/psychedelics-db/tree/main/app/"
    click UI "https://github.com/yuconnorl/psychedelics-db/tree/main/src/components"
    click API_Legacy "https://github.com/yuconnorl/psychedelics-db/tree/main/app/api"
    click API_V2 "https://github.com/yuconnorl/psychedelics-db/tree/main/app/apiv2"
    click CMS "https://github.com/yuconnorl/psychedelics-db/blob/main/src/payload.config.ts"
    click ALG "https://github.com/yuconnorl/psychedelics-db/tree/main/src/components/algolia"
    click LLM "https://github.com/yuconnorl/psychedelics-db/blob/main/app/apiv2/vector/route.ts"
    click UTIL "https://github.com/yuconnorl/psychedelics-db/tree/main/src/config"

    %% Styles
    classDef client fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef api fill:#ffe5b4,stroke:#333,stroke-width:2px;
    classDef cms fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef external fill:#c3f3c3,stroke:#333,stroke-width:2px;
    classDef utility fill:#e6e6fa,stroke:#333,stroke-width:2px;
```
