# traves-theberge/mikmaq-dictionary-api-and-mcp architecture

> Architecture diagram of the GitHub repository traves-theberge/mikmaq-dictionary-api-and-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/traves-theberge/mikmaq-dictionary-api-and-mcp
- Repository: https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp

## Overview

##### Project type and purpose
- This is a backend-only, microservices-style application comprising two primary services:
- The Mi’kmaq Dictionary RESTful API (Express.js, TypeScript)
- The MCP (Model Context Protocol) server for IDE/AI integration (also TypeScript/Express)
- Purpose: serve in-memory Mi’kmaq↔English dictionary lookups and expose a JSON-RPC interface for AI/IDE assistants.

##### File structure
- Top-level “src/” implements the Dictionary API:
- controllers/ → HTTP handlers
- services/ → business logic & in-memory dictionary loading (dictionary.json)
- routes/ → Express route definitions
- middleware/ → CORS, rate limiting, security headers, error handling
- “Mcp/” subfolder: a separate Node service implementing the JSON-RPC MCP server:
- index.ts → MCP server entry point
- dictionary-client.ts → HTTP client wrapper calling the Dictionary API
- Configuration & orchestration: Dockerfile(s), docker-compose.yml, tsconfig.json, jest.config.js.
- Test suites under “tests/” validate controllers, services, integration flows.

##### Key insights from README
- Two Docker Compose services share a user-defined network:
- mikmaq-dictionary-api: port 3000, serves HTTP REST API
- mcp-mikmaq-mcp-server: MCP JSON-RPC endpoints for IDE tooling
- Core data store is a read-only dictionary.json loaded into memory for sub-ms lookups.
- Standard layered architecture (routing → controllers → services → data).

1. Client(s):
– AI Assistant / IDE (via MCP JSON-RPC)
– External Applications / CLI / Browser (HTTP REST)
2. Docker Compose Network
3. Service: Dictionary API
– Express Middleware (security, CORS, rate limiter)
– Router → Controllers → DictionaryService
– In-memory Data Store (dictionary.json)
4. Service: MCP Server
– JSON-RPC Endpoint
– dictionary-client.ts (HTTP client) → calls Dictionary API
5. Data Artifact: dictionary.json (volume mount/read-only)
– External Client → HTTP REST → Dictionary API
– MCP Server → HTTP Client → Dictionary API
– Dictionary API loads dictionary.json at startup into in-memory index
– IDE/AI ↔ JSON-RPC ↔ MCP Server
– Docker Compose orchestrates TCP/network connectivity
c. Architectural patterns and design principles:
– Layered MVC-style within each service (routes/controllers/services)
– Single responsibility: API handles REST, MCP handles RPC
– In-memory indexing for ultra-fast lookups (no external DB)
– Containerized microservices connected by a Docker network
– Test suites enforce 100% coverage of core logic
d. Relevant technologies:
– Node.js, TypeScript, Express.js
– Docker, Docker Compose
– JSON-RPC for MCP
– Jest for testing

##### Final recommendations
- Drill down into the API container to expose the layered structure.
- Optionally, include a small inset showing test suites hooking into services for continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Clients"
    Browser("External App/CLI/Browser"):::clients
    IDE("IDE/AI Assistant"):::clients
  end

  Browser -->|REST HTTP call| API_container
  IDE -->|JSON-RPC| MCP_container

  subgraph "Docker Compose Network: mcp_mikmaq-network"
    subgraph "Dictionary API Service"
      direction TB
      API_container["Dictionary API Service"]:::api
      API_entry("src/index.ts"):::api
      Middleware("Middleware (CORS, RateLimit, Security)"):::api
      Router("Router (dictionary routes)"):::api
      Controller("DictionaryController"):::api
      Service("DictionaryService"):::api
      DataStore["dictionary.json (in-memory)"]:::datastore

      API_container --> API_entry --> Middleware --> Router --> Controller --> Service --> DataStore
    end

    subgraph "MCP JSON-RPC Service"
      direction TB
      MCP_container["MCP JSON-RPC Service"]:::mcp
      MCP_entry("Mcp/src/index.ts"):::mcp
      RPC("JSON-RPC Endpoint"):::mcp
      Client("Mcp/src/dictionary-client.ts"):::mcp

      MCP_container --> MCP_entry --> RPC --> Client
      Client -->|HTTP call| API_entry
    end
  end

  subgraph "Configuration & Tooling"
    Dockerfile("Dockerfile"):::config
    Compose("docker-compose.yml"):::config
    TSConfig("tsconfig.json"):::config
    JestConfig("jest.config.js"):::config
    Package("package.json"):::config
  end

  subgraph "Test Suites"
    DC_Test("tests/controllers/DictionaryController.test.ts"):::tests
    DS_Test("tests/services/DictionaryService.test.ts"):::tests
    API_Test("tests/integration/api.test.ts"):::tests
    Setup("tests/setup.ts"):::tests

    DC_Test --> DS_Test --> API_Test --> Setup
  end

  classDef api fill:#D0E8FF,stroke:#000,stroke-width:1px
  classDef mcp fill:#D0FFD8,stroke:#000,stroke-width:1px
  classDef datastore fill:#CCCCCC,stroke:#000,stroke-width:1px
  classDef clients fill:#F0F0F0,stroke:#000,stroke-width:1px
  classDef config fill:#F9F9F9,stroke:#000,stroke-width:1px
  classDef tests fill:#FFE4E1,stroke:#000,stroke-width:1px

  click API_entry "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/src/index.ts"
  click Router "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/src/routes/dictionary.ts"
  click Controller "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/src/controllers/DictionaryController.ts"
  click Service "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/src/services/DictionaryService.ts"
  click Middleware "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/src/middleware/index.ts"
  click DataStore "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/dictionary.json"
  click MCP_entry "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/Mcp/src/index.ts"
  click Client "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/Mcp/src/dictionary-client.ts"
  click Dockerfile "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/tree/main/Dockerfile"
  click Compose "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/docker-compose.yml"
  click TSConfig "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/tsconfig.json"
  click JestConfig "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/jest.config.js"
  click Package "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/package.json"
  click DC_Test "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/tests/controllers/DictionaryController.test.ts"
  click DS_Test "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/tests/services/DictionaryService.test.ts"
  click API_Test "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/tests/integration/api.test.ts"
  click Setup "https://github.com/traves-theberge/mikmaq-dictionary-api-and-mcp/blob/main/tests/setup.ts"
```
