# parth-420/synapse architecture

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

- Interactive diagram: https://gitdiagram.com/parth-420/synapse
- Repository: https://github.com/parth-420/synapse

## Overview

##### Project Type and Purpose
- Synapse is a full-stack web application designed to serve as a "Second Brain" for users—allowing them to store, organize, and retrieve diverse content (notes, quotes, links, etc.) with semantic and vector search capabilities.
- It integrates AI (via the Gemini API) for generating comprehensible answers and leverages MongoDB Atlas with a vector search index for advanced content retrieval.

##### Analyzing the File Structure
- The top-level structure reveals a clear Next.js App Router structure in the “app” directory with pages and layouts for home, dashboard, onboarding, and API routes.
- The “app/api” directory houses various API endpoints:
– auth (for NextAuth-based user authentication)
– entries (for handling creation and retrieval of content entries)
– search (for executing vector-based semantic searches)
– stats (for analytics)
- The “dashboard” sub-directory under “app” exposes front-end pages for interacting with the stored content (add, chat, view, write).
- Reusable UI components reside in the “components/ui” folder, and custom hooks are in the “hooks” folder.
- The “lib” directory contains utility libraries essential for integrating third-party services (gemini.ts for AI embeddings, mongodb.ts for database interactions) and TypeScript types.
- Configuration files and environment variables (documented in the README) further indicate dependencies like NextAuth, MongoDB, and Gemini API.

##### Key Components & Their Relationships
a. Frontend (Next.js Application):
– Pages and layouts in “app” and “dashboard” represent the user interface.
– UI components from “components/ui” and providers (session-provider, theme-provider) ensure a consistent design.
– Custom hooks like “use-toast” support UI notifications.
b. API Endpoints:
– Authentication: Managed in “app/api/auth/[...nextauth]/route.ts”, using NextAuth.js for user management.
– Entries Management: “app/api/entries/route.ts” handles creating and listing content entries.
– Search: “app/api/search/route.ts” implements vector search for semantic queries.
– Statistics: “app/api/stats/route.ts” offers usage analytics for the platform.
c. Database:
– MongoDB Atlas serves as the primary data store, using a vector search index (configured with a 768-dimensional “embedding” field) to facilitate semantic searches.
– The “lib/mongodb.ts” file contains helper functions to connect and interact with MongoDB.
d. AI Integration:
– The “lib/gemini.ts” file is crucial for communicating with the Gemini API to generate embeddings for entries and to support AI-powered answer generation.
e. Authentication & Environment Setup:
– NextAuth.js is integrated via API routes and the NextAuth configuration in “app/api/auth”.
– Environment variables (as documented in the README) must be set up for MongoDB, Gemini, and NextAuth.

##### Architectural Patterns and Design Principles
- Modern full-stack Next.js application structure with clear separations between frontend pages and backend API routes.
- Use of API Routes follows a RESTful or RPC style. Each API sub-folder (auth, entries, search, stats) encapsulates a distinct responsibility.
- Component-based design: “components/ui” includes a modular UI approach ensuring reusability.
- Integration with external services (MongoDB Atlas for database and Gemini for AI) supports a microservice-like interaction, even though it’s part of a monorepo.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Frontend Layer
    subgraph "Client/Frontend Layer"
        A0["App Layout (Next.js)"]:::frontend
        A1["Home Page (Next.js)"]:::frontend
        A3["GetStarted Page (Next.js)"]:::frontend
        A8["Dashboard Layout (Next.js)"]:::frontend
        A2["Dashboard Page (Next.js)"]:::frontend
        A4["UI Components"]:::ui
        A5["Session Provider"]:::ui
        A6["Theme Provider"]:::ui
        A7["Custom Hook (use-toast)"]:::hook
    end

    %% API Layer
    subgraph "API Layer"
        B1["Auth API"]:::api
        B2["Entries API"]:::api
        B3["Search API"]:::api
        B4["Stats API"]:::api
    end

    %% Database Layer
    subgraph "Database Layer"
        C1["Database Integration"]:::db
        C2["MongoDB Atlas<br>Vector Search Index"]:::db
    end

    %% External Integrations
    subgraph "External Integrations"
        D1["Gemini API"]:::external
    end

    %% Relationships within Frontend
    A0 --> A1
    A0 --> A3
    A8 --> A2

    %% Frontend to API interactions
    A1 -->|"login"| B1
    A2 -->|"CRUD_operations"| B2
    A2 -->|"semantic_search"| B3
    A2 -->|"analytics"| B4

    %% API to Database interactions via Database Integration
    B1 -->|"CRUD"| C1
    B2 -->|"CRUD"| C1
    B3 -->|"search"| C1
    B4 -->|"analytics"| C1
    C1 -->|"connects_to"| C2

    %% API and External Integration
    B3 -->|"AI_embedding"| D1

    %% Click Events
    click A0 "https://github.com/parth-420/synapse/blob/main/app/layout.tsx"
    click A1 "https://github.com/parth-420/synapse/blob/main/app/page.tsx"
    click A3 "https://github.com/parth-420/synapse/blob/main/app/getstarted/page.tsx"
    click A8 "https://github.com/parth-420/synapse/blob/main/app/dashboard/layout.tsx"
    click A2 "https://github.com/parth-420/synapse/blob/main/app/dashboard/page.tsx"
    click A4 "https://github.com/parth-420/synapse/tree/main/components/ui"
    click A5 "https://github.com/parth-420/synapse/blob/main/components/session-provider.tsx"
    click A6 "https://github.com/parth-420/synapse/blob/main/components/theme-provider.tsx"
    click A7 "https://github.com/parth-420/synapse/blob/main/hooks/use-toast.ts"
    click B1 "https://github.com/parth-420/synapse/blob/main/app/api/auth/[...nextauth]/route.ts"
    click B2 "https://github.com/parth-420/synapse/blob/main/app/api/entries/route.ts"
    click B3 "https://github.com/parth-420/synapse/blob/main/app/api/search/route.ts"
    click B4 "https://github.com/parth-420/synapse/blob/main/app/api/stats/route.ts"
    click C1 "https://github.com/parth-420/synapse/blob/main/lib/mongodb.ts"
    click D1 "https://github.com/parth-420/synapse/blob/main/lib/gemini.ts"

    %% Styles
    classDef frontend fill:#a2d9ff,stroke:#1f618d,stroke-width:2px;
    classDef api fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef db fill:#abebc6,stroke:#239b56,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef ui fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef hook fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
