# devagarwal2/map-proj architecture

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

- Interactive diagram: https://gitdiagram.com/devagarwal2/map-proj
- Repository: https://github.com/devagarwal2/map-proj

## Overview

1. **Overall shape**
   - This is a single Next.js 15 App Router application, not a multi-service backend.
   - The repo is centered on a marketplace-style UI plus one server-side chat API route that proxies requests to OpenRouter.

2. **Primary user-facing surface**
   - `app/page.tsx` is the main entry page for the marketplace.
   - It is composed from the reusable UI pieces in `components/`, especially `header.tsx`, `agent-card.tsx`, and `chat-interface.tsx`.

3. **Static marketplace data**
   - Agent catalog content lives in `lib/data.ts` with shared TypeScript shapes in `lib/types.ts`.
   - This is the source of truth for the six specialized agents described in the README, and it likely drives card rendering, category labels, and search/filter behavior.

4. **Client-side marketplace interactions**
   - Search and filtering appear to be handled in the frontend against the static agent dataset.
   - There is no database or persistence layer in the repo, so marketplace state is primarily client-side and ephemeral.

5. **Chat subsystem**
   - `components/chat-interface.tsx` is the interactive chat surface.
   - It is the main boundary where the browser sends user prompts, selected agent context, and file attachments into the AI workflow.

6. **Server boundary for AI calls**
   - `app/api/chat/route.ts` is the only explicit backend endpoint.
   - It acts as an adapter between the browser and OpenRouter, keeping the API key on the server side and returning streamed chat responses to the client.

7. **External AI dependency**
   - The application depends on OpenRouter and the model `arcee-ai/trinity-large-preview:free`.
   - `OPENROUTER_API_KEY` is the key runtime secret; without it the chat backend cannot function.

8. **File upload and content ingestion**
   - The README indicates the chat interface accepts PDFs, images, text, and code files.
   - Architecturally, this means the client handles upload/preview interaction, then packages file content or metadata into the chat request path for model processing.

9. **UI system and design layer**
   - The app uses Tailwind CSS with shadcn/ui primitives under `components/ui/`.
   - These components provide the dialog, card, button, input, textarea, avatar, badge, separator, and scroll-area building blocks that make the marketplace and chat UI consistent.

10. **Theme and layout**
   - `app/layout.tsx` wraps the app with `components/theme-provider.tsx`, which uses `next-themes` for dark-mode-first theming.
   - `app/globals.css` defines the global styling baseline and supports the clean dark visual design.

11. **Runtime and deployment boundaries**
   - The app runs as a Next.js Node runtime in development or inside Docker for deployment.
   - `Dockerfile` and `docker-compose.yml` provide containerized execution; the README also references a production compose setup and optional nginx reverse proxy.

12. **What is not present**
   - There is no evidence of a database, authentication system, job queue, or background worker.
   - That makes this an MVP architecture: static catalog + interactive chat + external LLM API, with minimal server-side surface area.

13. **Useful diagram framing**
   - A good architecture diagram would show:
     - Browser/UI shell on top
     - Static agent catalog and reusable UI components on the left
     - Chat UI calling the `/api/chat` server route in the middle
     - OpenRouter as the external AI service on the right
     - Docker/Compose as the deployment wrapper around the Next.js app

Main entry points: [`components/chat-interface.tsx`](https://github.com/devagarwal2/map-proj/blob/main/components/chat-interface.tsx) (Chat interface), [`app/page.tsx`](https://github.com/devagarwal2/map-proj/blob/main/app/page.tsx) (Home page), [`components/agent-card.tsx`](https://github.com/devagarwal2/map-proj/blob/main/components/agent-card.tsx) (Agent card), [`components/theme-provider.tsx`](https://github.com/devagarwal2/map-proj/blob/main/components/theme-provider.tsx) (Theme provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_app_page["Home page<br/>Next page<br/>[page.tsx]"]
  node_node_app_layout["App layout<br/>Next layout<br/>[layout.tsx]"]
  node_node_app_globals["Global styles<br/>CSS base<br/>[globals.css]"]
end

subgraph group_group_marketplace["Marketplace"]
  node_node_header["Header<br/>UI section<br/>[header.tsx]"]
  node_node_agent_card["Agent card<br/>Marketplace card<br/>[agent-card.tsx]"]
  node_node_catalog_data["Agent catalog<br/>Static data<br/>[data.ts]"]
  node_node_catalog_types["Catalog types<br/>Type definitions<br/>[types.ts]"]
end

subgraph group_group_chat["Chat Pipeline"]
  node_node_chat_interface["Chat interface<br/>Client chat<br/>[chat-interface.tsx]"]
  node_node_chat_route["Chat API<br/>Route handler<br/>[route.ts]"]
  node_node_openrouter(("OpenRouter<br/>LLM provider"))
end

subgraph group_group_ui["UI System"]
  node_node_theme_provider["Theme provider<br/>Theme wrapper<br/>[theme-provider.tsx]"]
  node_node_ui_button["Button<br/>UI primitive<br/>[button.tsx]"]
  node_node_ui_card["Card<br/>UI primitive<br/>[card.tsx]"]
  node_node_ui_input["Input<br/>UI primitive<br/>[input.tsx]"]
  node_node_ui_textarea["Textarea<br/>UI primitive<br/>[textarea.tsx]"]
  node_node_ui_dialog["Dialog<br/>UI primitive<br/>[dialog.tsx]"]
  node_node_ui_scroll["Scroll area<br/>UI primitive<br/>[scroll-area.tsx]"]
end

subgraph group_group_runtime["Runtime & Deploy"]
  node_node_dockerfile["Dockerfile<br/>Container image"]
  node_node_compose["Compose<br/>Deployment config<br/>[docker-compose.yml]"]
end

node_node_app_layout -->|"wraps"| node_node_theme_provider
node_node_app_layout -->|"loads"| node_node_app_globals
node_node_app_page -->|"renders"| node_node_header
node_node_app_page -->|"renders"| node_node_agent_card
node_node_app_page -->|"includes"| node_node_chat_interface
node_node_agent_card -->|"reads"| node_node_catalog_data
node_node_catalog_data -->|"uses"| node_node_catalog_types
node_node_chat_interface -->|"calls"| node_node_chat_route
node_node_chat_route -->|"proxies to"| node_node_openrouter
node_node_chat_interface -->|"uses"| node_node_ui_input
node_node_chat_interface -->|"uses"| node_node_ui_textarea
node_node_chat_interface -->|"uses"| node_node_ui_button
node_node_chat_interface -->|"uses"| node_node_ui_dialog
node_node_chat_interface -->|"uses"| node_node_ui_scroll
node_node_agent_card -->|"uses"| node_node_ui_card
node_node_header -->|"uses"| node_node_ui_button
node_node_theme_provider -.->|"supports"| node_node_ui_dialog
node_node_theme_provider -.->|"supports"| node_node_ui_card
node_node_dockerfile -->|"paired with"| node_node_compose
node_node_compose -.->|"runs"| node_node_app_page

click node_node_app_page "https://github.com/devagarwal2/map-proj/blob/main/app/page.tsx"
click node_node_app_layout "https://github.com/devagarwal2/map-proj/blob/main/app/layout.tsx"
click node_node_app_globals "https://github.com/devagarwal2/map-proj/blob/main/app/globals.css"
click node_node_header "https://github.com/devagarwal2/map-proj/blob/main/components/header.tsx"
click node_node_agent_card "https://github.com/devagarwal2/map-proj/blob/main/components/agent-card.tsx"
click node_node_catalog_data "https://github.com/devagarwal2/map-proj/blob/main/lib/data.ts"
click node_node_catalog_types "https://github.com/devagarwal2/map-proj/blob/main/lib/types.ts"
click node_node_chat_interface "https://github.com/devagarwal2/map-proj/blob/main/components/chat-interface.tsx"
click node_node_chat_route "https://github.com/devagarwal2/map-proj/blob/main/app/api/chat/route.ts"
click node_node_theme_provider "https://github.com/devagarwal2/map-proj/blob/main/components/theme-provider.tsx"
click node_node_ui_button "https://github.com/devagarwal2/map-proj/blob/main/components/ui/button.tsx"
click node_node_ui_card "https://github.com/devagarwal2/map-proj/blob/main/components/ui/card.tsx"
click node_node_ui_input "https://github.com/devagarwal2/map-proj/blob/main/components/ui/input.tsx"
click node_node_ui_textarea "https://github.com/devagarwal2/map-proj/blob/main/components/ui/textarea.tsx"
click node_node_ui_dialog "https://github.com/devagarwal2/map-proj/blob/main/components/ui/dialog.tsx"
click node_node_ui_scroll "https://github.com/devagarwal2/map-proj/blob/main/components/ui/scroll-area.tsx"
click node_node_dockerfile "https://github.com/devagarwal2/map-proj/tree/main/Dockerfile"
click node_node_compose "https://github.com/devagarwal2/map-proj/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_app_page,node_node_app_layout,node_node_app_globals toneBlue
class node_node_header,node_node_agent_card,node_node_catalog_data,node_node_catalog_types toneAmber
class node_node_chat_interface,node_node_chat_route,node_node_openrouter toneMint
class node_node_theme_provider,node_node_ui_button,node_node_ui_card,node_node_ui_input,node_node_ui_textarea,node_node_ui_dialog,node_node_ui_scroll toneRose
class node_node_dockerfile,node_node_compose toneIndigo
```

## Components

### App Shell

Next.js routing, layout, and global styling.

- [Home page](https://github.com/devagarwal2/map-proj/blob/main/app/page.tsx): Next page · Main marketplace entry rendered by the App Router. · `app/page.tsx`
- [App layout](https://github.com/devagarwal2/map-proj/blob/main/app/layout.tsx): Next layout · Wraps the application shell and theme provider. · `app/layout.tsx`
- [Global styles](https://github.com/devagarwal2/map-proj/blob/main/app/globals.css): CSS base · Global styling baseline for the app. · `app/globals.css`

### Marketplace

Static agent catalog and homepage composition.

- [Header](https://github.com/devagarwal2/map-proj/blob/main/components/header.tsx): UI section · Top-level marketplace header and navigation surface. · `components/header.tsx`
- [Agent card](https://github.com/devagarwal2/map-proj/blob/main/components/agent-card.tsx): Marketplace card · Reusable presentation for agent listings. · `components/agent-card.tsx`
- [Agent catalog](https://github.com/devagarwal2/map-proj/blob/main/lib/data.ts): Static data · Source of truth for the marketplace agent set. · `lib/data.ts`
- [Catalog types](https://github.com/devagarwal2/map-proj/blob/main/lib/types.ts): Type definitions · Shared TypeScript shapes for agent data. · `lib/types.ts`

### Chat Pipeline

Client chat UI and server-side OpenRouter adapter.

- [Chat interface](https://github.com/devagarwal2/map-proj/blob/main/components/chat-interface.tsx): Client chat · Interactive chat surface for prompts and attachments. · `components/chat-interface.tsx`
- [Chat API](https://github.com/devagarwal2/map-proj/blob/main/app/api/chat/route.ts): Route handler · Server adapter that proxies chat requests to OpenRouter. · `app/api/chat/route.ts`
- **OpenRouter**: LLM provider · External AI service used for streamed chat responses.

### UI System

Reusable UI primitives and theming.

- [Theme provider](https://github.com/devagarwal2/map-proj/blob/main/components/theme-provider.tsx): Theme wrapper · next-themes integration for dark-mode-first theming. · `components/theme-provider.tsx`
- [Button](https://github.com/devagarwal2/map-proj/blob/main/components/ui/button.tsx): UI primitive · Shared button primitive used across the interface. · `components/ui/button.tsx`
- [Card](https://github.com/devagarwal2/map-proj/blob/main/components/ui/card.tsx): UI primitive · Surface primitive used for agent and content panels. · `components/ui/card.tsx`
- [Input](https://github.com/devagarwal2/map-proj/blob/main/components/ui/input.tsx): UI primitive · Text input primitive for search and form fields. · `components/ui/input.tsx`
- [Textarea](https://github.com/devagarwal2/map-proj/blob/main/components/ui/textarea.tsx): UI primitive · Multiline input primitive for chat composition. · `components/ui/textarea.tsx`
- [Dialog](https://github.com/devagarwal2/map-proj/blob/main/components/ui/dialog.tsx): UI primitive · Modal primitive for overlays and focused interactions. · `components/ui/dialog.tsx`
- [Scroll area](https://github.com/devagarwal2/map-proj/blob/main/components/ui/scroll-area.tsx): UI primitive · Scrollable container for long chat or marketplace content. · `components/ui/scroll-area.tsx`

### Runtime & Deploy

Containerized execution and app runtime boundaries.

- [Dockerfile](https://github.com/devagarwal2/map-proj/tree/main/Dockerfile): Container image · Builds the Next.js app into a container image. · `Dockerfile`
- [Compose](https://github.com/devagarwal2/map-proj/blob/main/docker-compose.yml): Deployment config · Container orchestration for local or production deployment. · `docker-compose.yml`

## Connections

- App layout → Theme provider: wraps · Provides theme context for the application shell.
- App layout → Global styles: loads · Applies the global CSS baseline.
- Home page → Header: renders · Composes the marketplace header on the home page.
- Home page → Agent card: renders · Uses agent cards to present the catalog.
- Home page → Chat interface: includes · Embeds the interactive chat surface in the homepage.
- Agent card → Agent catalog: reads · Maps catalog entries into card views.
- Agent catalog → Catalog types: uses · Typed against the shared agent data shapes.
- Chat interface → Chat API: calls · Sends prompts and attachments to the server route.
- Chat API → OpenRouter: proxies to · Forwards chat requests to the external model provider.
- Chat interface → Input: uses · Uses input fields for search and chat composition.
- Chat interface → Textarea: uses · Uses multiline input for message entry.
- Chat interface → Button: uses · Uses shared buttons for actions and submit controls.
- Chat interface → Dialog: uses · Uses modal interactions for attachments or focused flows.
- Chat interface → Scroll area: uses · Uses scrollable regions for conversation history.
- Agent card → Card: uses · Built on the shared card primitive.
- Header → Button: uses · Relies on shared buttons for navigation and actions.
- Theme provider → Dialog: supports · Theme context applies to modal surfaces and overlays.
- Theme provider → Card: supports · Theme context styles shared content surfaces.
- Dockerfile → Compose: paired with · Container image is orchestrated by compose.
- Compose → Home page: runs · Deploys the Next.js application runtime.
