# chatmcp/mcp-directory architecture

> Architecture diagram of the GitHub repository chatmcp/mcp-directory, 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/chatmcp/mcp-directory
- Repository: https://github.com/chatmcp/mcp-directory

## Overview

##### Main Components

- Web Frontend:
- The "app" directory contains Next.js “app” directory routing files including pages like [slug], [name], category pages, and policy pages.
- The "components" and "templates" folders provide reusable UI components and prebuilt layouts (e.g., the Tailspark landing page theme).
- Global styling is managed via Tailwind configurations, CSS files (globals.css, styles.css), and theme providers in the "providers" folder.

- API Backend:
- The "app/api" folder holds several API routes (e.g., submit-project, summarize-project) which serve as the backend endpoints for processing project submissions and summaries.
- The API endpoints are implemented in route.ts files, following Next.js API Routes conventions.

- Data & Models:
- The "data" folder includes an SQL file (install.sql) meant for preparing the database (likely on Supabase).
- The "models" directory defines data models for categories, projects, users, and the database connection. This suggests that the application interacts with structured data stored in a database.

- Services & Integrations:
- The "services" folder demonstrates integration with external systems and functionality layers. For instance, the subfolder "services/llms" (with openai.ts) shows the integration with an LLM (e.g., OpenAI), while "services/reader" (with jina.ts) may be used for text processing or search.
- Additional services provide logic for extracting and summarizing project details ("services/prompts").

- Static Assets & Public Content:
- The "public" directory contains static files (robots.txt, sitemap, ads.txt, etc.) that support SEO and external integration.
- Assets for the landing pages are also provided under "templates".

##### Relationships and Interactions

- The Frontend consumes data from both the API backend and static files. Pages in the "app" directory may request or send data to API routes (e.g., project submission or summarization).
- API routes act as the intermediary between the user interface and the database. They likely use models (from the "models" folder) and services (from the "services" folder) to process business logic.
- The database (set up via Supabase and defined by the SQL in "data") stores persistent data for projects, categories, and user-related information.
- External integrations (OpenAI and possibly Jina for reading/indexing content) are orchestrated in the services layer to enhance functionality and add dynamic processing capabilities.

##### Architectural Patterns & Design Principles

- Next.js Routing and API: The application follows the file-system based routing of Next.js, with segregated directories for page views and API handlers.
- Separation of Concerns: The codebase is organized to separate presentation (UI components and templates), data modeling (models), business logic (services), and database interactions (data SQL scripts).
- Modularization & Reusability: The presence of components, templates, and providers indicates a design focused on reusable parts.
- Integration with External Services: The architecture includes modules intended for integration with LLMs (using OpenAI) and possibly search or processing via Jina.

##### Relevant Technologies, Frameworks, and Libraries

- Next.js and React (with TypeScript) for building and organizing the app.
- Tailwind CSS, as indicated by tailwind.config.ts and various style files.
- Supabase for the database layer (as described in the README and supported by data/install.sql).
- External services integrations (OpenAI via services/llms/openai.ts and Jina via services/reader/jina.ts).
- Various project-specific prompts and processing scripts (services/prompts).

##### Specific Elements

- Main Components:
- Frontend/UI: app directory, components, and templates.
- API/Backend: app/api routes.
- Data Layer: Supabase database connection (data/install.sql, models).
- Services/Integrations: services/llms, services/prompts, services/reader.

- Data Flow:

- Architecture Patterns:
- How Next.js file-based routing is leveraged.
- That API endpoints use serverless functions (route.ts files) to process business logic.
- Modular design patterns (the separation of models, services, and UI components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        pages["Frontend Pages (app)"]:::frontend
        ui["Reusable UI Components (components)"]:::frontend
        templates["Site Templates (templates/tailspark)"]:::frontend
        styling["Global Styling & Theme"]:::css
        globalcss["Global CSS (app/globals.css)"]:::css
        styles["Styles (app/(default)/styles.css)"]:::css
        theme["Theme Provider (providers/theme.tsx)"]:::css
        tailwindconfig["Tailwind Config (tailwind.config.ts)"]:::css
        postcssconfig["PostCSS Config (postcss.config.mjs)"]:::css
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        apiRoutes["API Routes (app/api)"]:::backend
        submit["Submit Project Endpoint (app/api/submit-project/route.ts)"]:::backend
        summarize["Summarize Project Endpoint (app/api/summarize-project/route.ts)"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        database["Supabase Database"]:::database
        dbSetup["DB Setup (data/install.sql)"]:::database
        modelsNode["Data Models (models)"]:::database
    end

    %% Services & Integrations
    subgraph "Services & Integrations"
        direction TB
        llm["LLM Integration (services/llms/openai.ts)"]:::services
        reader["Content Reader (services/reader/jina.ts)"]:::services
        prompts["Project Prompts (services/prompts)"]:::services
        projectService["Project Service (services/project.ts)"]:::services
    end

    %% Static Assets
    subgraph "Static Assets"
        direction TB
        publicAssets["Public Files (public)"]:::assets
        landingAssets["Landing Assets (templates/tailspark/landing/assets)"]:::assets
    end

    %% Connections between layers
    pages -->|"calls"| apiRoutes
    apiRoutes -->|"processes"| submit
    apiRoutes -->|"processes"| summarize
    apiRoutes -->|"queries"| database
    submit -->|"uses"| modelsNode
    summarize -->|"uses"| modelsNode
    apiRoutes -->|"calls"| llm
    apiRoutes -->|"calls"| reader
    apiRoutes -->|"calls"| prompts
    apiRoutes -->|"calls"| projectService

    %% UI to Styling and Templates
    pages --- ui
    pages --- templates
    styling --- globalcss
    styling --- styles
    styling --- theme
    styling --- tailwindconfig
    styling --- postcssconfig

    %% Frontend loading static assets
    pages -->|"loads"| publicAssets
    templates -->|"includes"| landingAssets

    %% Database internal connections
    database --- dbSetup
    database --- modelsNode

    %% Click Events
    click pages "https://github.com/chatmcp/mcp-directory/tree/main/app"
    click ui "https://github.com/chatmcp/mcp-directory/tree/main/components"
    click templates "https://github.com/chatmcp/mcp-directory/tree/main/templates/tailspark"
    click globalcss "https://github.com/chatmcp/mcp-directory/blob/main/app/globals.css"
    click styles "https://github.com/chatmcp/mcp-directory/blob/main/app/(default)/styles.css"
    click theme "https://github.com/chatmcp/mcp-directory/blob/main/providers/theme.tsx"
    click tailwindconfig "https://github.com/chatmcp/mcp-directory/blob/main/tailwind.config.ts"
    click postcssconfig "https://github.com/chatmcp/mcp-directory/blob/main/postcss.config.mjs"
    click apiRoutes "https://github.com/chatmcp/mcp-directory/tree/main/app/api"
    click submit "https://github.com/chatmcp/mcp-directory/blob/main/app/api/submit-project/route.ts"
    click summarize "https://github.com/chatmcp/mcp-directory/blob/main/app/api/summarize-project/route.ts"
    click dbSetup "https://github.com/chatmcp/mcp-directory/blob/main/data/install.sql"
    click modelsNode "https://github.com/chatmcp/mcp-directory/tree/main/models"
    click llm "https://github.com/chatmcp/mcp-directory/blob/main/services/llms/openai.ts"
    click reader "https://github.com/chatmcp/mcp-directory/blob/main/services/reader/jina.ts"
    click prompts "https://github.com/chatmcp/mcp-directory/tree/main/services/prompts"
    click projectService "https://github.com/chatmcp/mcp-directory/blob/main/services/project.ts"
    click publicAssets "https://github.com/chatmcp/mcp-directory/tree/main/public"
    click landingAssets "https://github.com/chatmcp/mcp-directory/tree/main/templates/tailspark/landing/assets"

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#faa,stroke:#333,stroke-width:2px;
    classDef database fill:#afa,stroke:#333,stroke-width:2px;
    classDef services fill:#ffd,stroke:#333,stroke-width:2px;
    classDef assets fill:#cff,stroke:#333,stroke-width:2px;
    classDef css fill:#fdc,stroke:#333,stroke-width:2px;
```
