# anmolsaini16/mapcn architecture

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

- Interactive diagram: https://gitdiagram.com/anmolsaini16/mapcn
- Repository: https://github.com/anmolsaini16/mapcn

## Overview

#### Purpose and Runtime
mapcn is a Next.js/React site and distributable component registry for ready-to-use MapLibre GL map UI components. It uses Tailwind and shadcn/ui conventions, with CARTO/OpenStreetMap-compatible basemap providers. Primary application shell: `src/app/layout.tsx`, `src/app/(main)/layout.tsx`, and `src/styles/globals.css`.

#### Site Entry Points
The landing page presents component examples at `src/app/(main)/(home)/page.tsx`. Documentation is routed under `src/app/(main)/docs`, while the block catalog is served by `src/app/(main)/blocks/page.tsx`. Individual installable block previews use dynamic routes at `src/app/(view)/view/[name]/page.tsx`.

#### Core Map Component Layer
The foundational React/MapLibre-facing implementation is `src/registry/map.tsx`. Documentation examples exercise its declarative map, layer, marker, popup, route, control, GeoJSON, cluster, and arc capabilities, notably under `src/app/(main)/docs/_components/examples` and `src/app/(main)/docs/basic-map/page.tsx`. This registry code is the source material consumers install or adapt.

#### Registry and Distribution Boundary
Registry metadata describes published components in `registry.json`; generated/public registry payloads are in `public/r/registry.json` and per-block JSON files such as `public/r/analytics-map.json`. The registry block source lives under `src/registry/blocks`, for example `src/registry/blocks/analytics-map/page.tsx`, `src/registry/blocks/store-locator/page.tsx`, and `src/registry/blocks/logistics-network/page.tsx`. This separates reusable block source from the website that documents and previews it.

#### Block Preview and Source Flow
The blocks catalog loads block definitions through `src/lib/blocks.ts`, renders previews using `src/app/(main)/blocks/_components/block-preview.tsx`, and exposes inspectable source with `src/app/(main)/blocks/_components/block-viewer-code.tsx`. `src/lib/get-block-file-source.ts` provides the source-reading boundary. Dynamic `/view/[name]` pages provide focused rendered previews, likely suitable for iframe embedding via `src/app/(main)/blocks/_components/iframe-preview.tsx`.

#### Documentation and Discovery
Docs pages are organized by capability (`src/app/(main)/docs/markers/page.tsx`, `src/app/(main)/docs/routes/page.tsx`, `src/app/(main)/docs/geojson/page.tsx`) and assembled with `src/app/(main)/docs/_components/docs.tsx`, navigation/sidebar components, and live previews. Shared site navigation and responsive header behavior are centralized in `src/lib/site-navigation.ts`, `src/components/header.tsx`, and `src/components/command-search.tsx`.

#### LLM-Facing Content
Catch-all LLM routes at `src/app/(main)/llm/[[...slug]]/route.ts` and `src/app/llms.txt/route.ts` expose machine-oriented documentation/content. Their generation and prompt logic are bounded in `src/lib/llm-content.ts` and `src/lib/llm-prompts.ts`, distinct from browser-rendered docs.

#### Infrastructure and External Dependencies
The runtime is Next.js with React/TypeScript, Tailwind/PostCSS, and shadcn/ui-style primitives under `src/components/ui`. Map rendering depends on MapLibre GL and external tile/style/data services selected by consumers; CARTO basemaps are the documented default and carry commercial-use terms. Registry import normalization is maintained by `scripts/fix-registry-imports.ts`.

Main entry points: [`src/registry/blocks`](https://github.com/anmolsaini16/mapcn/tree/main/src/registry/blocks) (Block source), [`src/app/layout.tsx`](https://github.com/anmolsaini16/mapcn/blob/main/src/app/layout.tsx) (Application shell), [`src/app/(main)/blocks/page.tsx`](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/blocks/page.tsx) (Block catalog), [`registry.json`](https://github.com/anmolsaini16/mapcn/blob/main/registry.json) (Registry metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Next.js site"]
  node_app_shell["Application shell<br/>Next.js layouts<br/>[layout.tsx]"]
  node_home["Landing page<br/>[page.tsx]"]
  node_docs["Documentation<br/>page system<br/>[docs.tsx]"]
  node_docs_examples["Map examples<br/>React examples"]
  node_site_navigation["Site navigation<br/>[site-navigation.ts]"]
  node_header["Header and search<br/>shared UI<br/>[header.tsx]"]
  node_blocks_catalog["Block catalog<br/>page<br/>[page.tsx]"]
  node_block_data["Block definitions<br/>catalog loader<br/>[blocks.ts]"]
  node_block_preview["Block preview<br/>preview UI<br/>[block-preview.tsx]"]
  node_block_source["Source viewer<br/>source boundary"]
  node_dynamic_preview["Focused block preview<br/>dynamic page<br/>[page.tsx]"]
end

subgraph group_maps["Map components"]
  node_map_component["Map component API<br/>React MapLibre registry<br/>[map.tsx]"]
  node_external_map_services{{"Tile, style, and data services<br/>external mapping providers"}}
end

subgraph group_registry["Registry distribution"]
  node_block_sources["Block source<br/>installable React blocks"]
  node_registry_manifest["Registry metadata<br/>registry manifest<br/>[registry.json]"]
  node_published_registry[("Published registry payloads<br/>public JSON<br/>[registry.json]")]
  node_registry_normalizer["Registry import normalizer<br/>build script"]
end

subgraph group_llm["LLM content"]
  node_llm_routes["LLM routes<br/>Next.js route handlers<br/>[route.ts]"]
  node_llm_content["LLM content generator<br/>content boundary<br/>[llm-content.ts]"]
  node_llms_txt["llms.txt route<br/>route handler<br/>[route.ts]"]
end

node_app_shell -->|"renders"| node_home
node_app_shell -->|"hosts"| node_docs
node_app_shell -->|"hosts"| node_blocks_catalog
node_site_navigation -->|"drives"| node_header
node_header -->|"shared by"| node_app_shell
node_home -->|"presents"| node_docs_examples
node_docs -->|"embeds"| node_docs_examples
node_docs_examples -->|"exercises"| node_map_component
node_map_component -->|"renders with"| node_external_map_services
node_blocks_catalog -->|"loads"| node_block_data
node_blocks_catalog -->|"renders"| node_block_preview
node_block_data -->|"selects"| node_block_sources
node_block_preview -->|"previews"| node_block_sources
node_block_source -->|"reads"| node_block_sources
node_dynamic_preview -->|"renders"| node_block_sources
node_block_sources -->|"composes"| node_map_component
node_registry_manifest -->|"describes"| node_block_sources
node_registry_normalizer -->|"normalizes imports for"| node_registry_manifest
node_registry_manifest -->|"publishes as"| node_published_registry
node_block_sources -->|"distributed as"| node_published_registry
node_llm_routes -->|"generates from"| node_llm_content
node_llms_txt -->|"serves"| node_llm_content

click node_app_shell "https://github.com/anmolsaini16/mapcn/blob/main/src/app/layout.tsx"
click node_home "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/(home)/page.tsx"
click node_docs "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/docs/_components/docs.tsx"
click node_docs_examples "https://github.com/anmolsaini16/mapcn/tree/main/src/app/(main)/docs/_components/examples"
click node_site_navigation "https://github.com/anmolsaini16/mapcn/blob/main/src/lib/site-navigation.ts"
click node_header "https://github.com/anmolsaini16/mapcn/blob/main/src/components/header.tsx"
click node_blocks_catalog "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/blocks/page.tsx"
click node_block_data "https://github.com/anmolsaini16/mapcn/blob/main/src/lib/blocks.ts"
click node_block_preview "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/blocks/_components/block-preview.tsx"
click node_block_source "https://github.com/anmolsaini16/mapcn/blob/main/src/lib/get-block-file-source.ts"
click node_dynamic_preview "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(view)/view/%5Bname%5D/page.tsx"
click node_map_component "https://github.com/anmolsaini16/mapcn/blob/main/src/registry/map.tsx"
click node_block_sources "https://github.com/anmolsaini16/mapcn/tree/main/src/registry/blocks"
click node_registry_manifest "https://github.com/anmolsaini16/mapcn/blob/main/registry.json"
click node_published_registry "https://github.com/anmolsaini16/mapcn/blob/main/public/r/registry.json"
click node_registry_normalizer "https://github.com/anmolsaini16/mapcn/blob/main/scripts/fix-registry-imports.ts"
click node_llm_routes "https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/llm/%5B%5B...slug%5D%5D/route.ts"
click node_llm_content "https://github.com/anmolsaini16/mapcn/blob/main/src/lib/llm-content.ts"
click node_llms_txt "https://github.com/anmolsaini16/mapcn/blob/main/src/app/llms.txt/route.ts"

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_app_shell,node_home,node_docs,node_docs_examples,node_site_navigation,node_header,node_blocks_catalog,node_block_data,node_block_preview,node_block_source,node_dynamic_preview toneBlue
class node_map_component,node_external_map_services toneAmber
class node_block_sources,node_registry_manifest,node_published_registry,node_registry_normalizer toneMint
class node_llm_routes,node_llm_content,node_llms_txt toneRose
```

## Components

### Next.js site

- [Application shell](https://github.com/anmolsaini16/mapcn/blob/main/src/app/layout.tsx): Next.js layouts · Provides global and main-site layout styling. · `src/app/layout.tsx`
- [Landing page](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/(home)/page.tsx): page · `src/app/(main)/(home)/page.tsx`
- [Documentation](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/docs/_components/docs.tsx): page system · Capability pages with live map examples. · `src/app/(main)/docs/_components/docs.tsx`
- [Map examples](https://github.com/anmolsaini16/mapcn/tree/main/src/app/(main)/docs/_components/examples): React examples · `src/app/(main)/docs/_components/examples`
- [Site navigation](https://github.com/anmolsaini16/mapcn/blob/main/src/lib/site-navigation.ts): navigation · `src/lib/site-navigation.ts`
- [Header and search](https://github.com/anmolsaini16/mapcn/blob/main/src/components/header.tsx): shared UI · `src/components/header.tsx`
- [Block catalog](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/blocks/page.tsx): page · `src/app/(main)/blocks/page.tsx`
- [Block definitions](https://github.com/anmolsaini16/mapcn/blob/main/src/lib/blocks.ts): catalog loader · `src/lib/blocks.ts`
- [Block preview](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/blocks/_components/block-preview.tsx): preview UI · `src/app/(main)/blocks/_components/block-preview.tsx`
- [Source viewer](https://github.com/anmolsaini16/mapcn/blob/main/src/lib/get-block-file-source.ts): source boundary · Reads inspectable block source. · `src/lib/get-block-file-source.ts`
- [Focused block preview](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(view)/view/%5Bname%5D/page.tsx): dynamic page · Renders an individual block by name. · `src/app/(view)/view/[name]/page.tsx`

### Map components

- [Map component API](https://github.com/anmolsaini16/mapcn/blob/main/src/registry/map.tsx): React MapLibre registry · Declarative maps, layers, markers, popups, routes, controls, GeoJSON, clusters, and arcs. · `src/registry/map.tsx`
- **Tile, style, and data services**: external mapping providers · Consumer-selected services; CARTO is the documented default.

### Registry distribution

- [Block source](https://github.com/anmolsaini16/mapcn/tree/main/src/registry/blocks): installable React blocks · `src/registry/blocks`
- [Registry metadata](https://github.com/anmolsaini16/mapcn/blob/main/registry.json): registry manifest · `registry.json`
- [Published registry payloads](https://github.com/anmolsaini16/mapcn/blob/main/public/r/registry.json): public JSON · Generated component and per-block installation payloads. · `public/r/registry.json`
- [Registry import normalizer](https://github.com/anmolsaini16/mapcn/blob/main/scripts/fix-registry-imports.ts): build script · `scripts/fix-registry-imports.ts`

### LLM content

- [LLM routes](https://github.com/anmolsaini16/mapcn/blob/main/src/app/(main)/llm/%5B%5B...slug%5D%5D/route.ts): Next.js route handlers · Serves machine-oriented documentation content. · `src/app/(main)/llm/[[...slug]]/route.ts`
- [LLM content generator](https://github.com/anmolsaini16/mapcn/blob/main/src/lib/llm-content.ts): content boundary · `src/lib/llm-content.ts`
- [llms.txt route](https://github.com/anmolsaini16/mapcn/blob/main/src/app/llms.txt/route.ts): route handler · `src/app/llms.txt/route.ts`

## Connections

- Application shell → Landing page: renders
- Application shell → Documentation: hosts
- Application shell → Block catalog: hosts
- Site navigation → Header and search: drives
- Header and search → Application shell: shared by
- Landing page → Map examples: presents
- Documentation → Map examples: embeds
- Map examples → Map component API: exercises
- Map component API → Tile, style, and data services: renders with
- Block catalog → Block definitions: loads
- Block catalog → Block preview: renders
- Block definitions → Block source: selects
- Block preview → Block source: previews
- Source viewer → Block source: reads
- Focused block preview → Block source: renders
- Block source → Map component API: composes
- Registry metadata → Block source: describes
- Registry import normalizer → Registry metadata: normalizes imports for
- Registry metadata → Published registry payloads: publishes as
- Block source → Published registry payloads: distributed as
- LLM routes → LLM content generator: generates from
- llms.txt route → LLM content generator: serves
