# devmantowhid/langtree architecture

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

- Interactive diagram: https://gitdiagram.com/devmantowhid/langtree
- Repository: https://github.com/devmantowhid/langtree

## Overview

1. **Repository shape**
   - This is a two-part monorepo: `frontend/` and `backend/`, with a root `package.json` coordinating installs/workspaces.
   - The architecture is intentionally split between a Next.js UI layer and an Express/Firebase API layer.

2. **Frontend subsystem**
   - `frontend/app/` is a Next.js App Router application.
   - Key entrypoints are `app/page.tsx` for the landing page, `app/layout.tsx` for global shell, and `app/[...slug]/page.tsx` for hierarchical, catch-all language/family routes.
   - `CommonLanguages.tsx` and `LanguageFamilies.tsx` appear to be reusable presentation components for browsing and navigation.

3. **Route model**
   - The frontend is built around a deep path structure that mirrors language ancestry.
   - The catch-all route means a single page module can render many nested URL shapes, which is important for representing a tree rather than a flat list.

4. **Backend API subsystem**
   - `backend/server.js` is the Node/Express entrypoint.
   - `backend/routes/languageRoutes.js` defines the REST surface, and `backend/controllers/languageController.js` contains the request handlers.
   - `backend/middlewares/errorHandler.js` centralizes API error formatting and response behavior.

5. **Database and integration boundary**
   - `backend/config/firebase-config.js` connects the server to Firebase Firestore.
   - Firestore is the primary persistence boundary; the frontend does not appear to talk to it directly.
   - This keeps all read/write and tree-resolution logic behind the API.

6. **Tree/ancestry data model**
   - The README describes a denormalized language tree: each record stores ancestry/path metadata instead of requiring runtime recursion.
   - That design supports fast lookup of a language plus its ancestors/descendants without multi-hop database traversal.

7. **Path reconstruction utilities**
   - `backend/utils/create_ancestry_chain.js` likely assembles the full ancestor chain for a requested language or slug path.
   - This is a key backend responsibility because the frontend route structure depends on exact ancestry order.
   - The architecture therefore uses backend-driven path validation/reconstruction rather than purely client-side routing.

8. **Seeding and data bootstrap**
   - `backend/utils/seedLanguage.js` and `backend/utils/seed_Data.js` are ingestion/bootstrap scripts for populating Firestore.
   - `backend/test-connection.js` is a small operational utility to verify Firestore connectivity.
   - These scripts indicate the data set is managed as a curated tree rather than an ad hoc runtime source.

9. **End-to-end request flow**
   - A user lands on the Next.js app, browses languages/families, or enters a deep ancestry URL.
   - The frontend requests language data from the Express API.
   - The backend queries Firestore, reconstructs or validates ancestry, and returns a tree-shaped payload.
   - The frontend renders the hierarchy and uses the returned path data to match the URL structure.

10. **Primary architectural boundary**
    - UI rendering and routing live in the frontend.
    - Tree semantics, search/path resolution, and persistence live in the backend.
    - That separation is the core design decision in the repo: the client is optimized for navigation, while the server owns language-graph logic and data access.

11. **Operational/deployment implications**
    - The README indicates a Next.js deployment model for the frontend and a separately hosted backend.
    - That means the frontend is environment-variable driven for API access, while the backend can be scaled or hosted independently.

12. **What an architecture diagram should emphasize**
    - Two deployable services: Next.js frontend and Express backend.
    - One external datastore: Firebase Firestore.
    - One critical algorithmic subsystem: ancestry/path reconstruction.
    - One central UX pattern: catch-all hierarchical routing over a denormalized language tree.

Main entry points: [`backend/controllers/languageController.js`](https://github.com/devmantowhid/langtree/blob/main/backend/controllers/languageController.js) (Language controller), [`backend/config/firebase-config.js`](https://github.com/devmantowhid/langtree/blob/main/backend/config/firebase-config.js) (Firebase config), [`frontend/app/[...slug]/page.tsx`](https://github.com/devmantowhid/langtree/blob/main/frontend/app/[...slug]/page.tsx) (Tree route), [`frontend/app/layout.tsx`](https://github.com/devmantowhid/langtree/blob/main/frontend/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Monorepo"]
  node_root_pkg["Root package<br/>workspace<br/>[package.json]"]
end

subgraph group_frontend["Frontend"]
  node_ui_shell["App shell<br/>next shell<br/>[layout.tsx]"]
  node_home_page["Landing page<br/>next page<br/>[page.tsx]"]
  node_catchall_route["Tree route<br/>catch-all page<br/>[page.tsx]"]
  node_common_langs["Common langs<br/>ui component"]
  node_language_families["Families view<br/>ui component"]
end

subgraph group_backend["Backend"]
  node_api_server["API server<br/>express entrypoint<br/>[server.js]"]
  node_language_routes["Language routes<br/>api routes<br/>[languageRoutes.js]"]
  node_language_controller["Language controller<br/>request handlers"]
  node_error_handler["Error handler<br/>middleware<br/>[errorHandler.js]"]
  node_firebase_config["Firebase config<br/>firestore client<br/>[firebase-config.js]"]
  node_ancestry_chain["Ancestry chain<br/>path utility"]
  node_seed_language["Seed language<br/>bootstrap script<br/>[seedLanguage.js]"]
  node_seed_data["Seed data<br/>bootstrap script<br/>[seed_Data.js]"]
  node_test_connection["Connection test<br/>ops script<br/>[test-connection.js]"]
end

node_root_pkg -->|"workspace"| node_ui_shell
node_root_pkg -->|"workspace"| node_api_server
node_ui_shell -->|"renders"| node_home_page
node_ui_shell -->|"wraps"| node_catchall_route
node_home_page -->|"uses"| node_common_langs
node_home_page -->|"uses"| node_language_families
node_catchall_route -->|"uses"| node_language_families
node_catchall_route -->|"fetches"| node_language_controller
node_api_server -->|"mounts"| node_language_routes
node_language_routes -->|"delegates"| node_language_controller
node_language_controller -->|"queries"| node_firebase_config
node_language_controller -->|"reconstructs"| node_ancestry_chain
node_language_controller -->|"fails through"| node_error_handler
node_ancestry_chain -->|"reads"| node_firebase_config
node_seed_language -->|"writes"| node_firebase_config
node_seed_data -->|"writes"| node_firebase_config
node_test_connection -->|"verifies"| node_firebase_config
node_language_routes -->|"returns"| node_error_handler
node_catchall_route -.->|"depends on"| node_ancestry_chain

click node_root_pkg "https://github.com/devmantowhid/langtree/blob/main/package.json"
click node_ui_shell "https://github.com/devmantowhid/langtree/blob/main/frontend/app/layout.tsx"
click node_home_page "https://github.com/devmantowhid/langtree/blob/main/frontend/app/page.tsx"
click node_catchall_route "https://github.com/devmantowhid/langtree/blob/main/frontend/app/[...slug]/page.tsx"
click node_common_langs "https://github.com/devmantowhid/langtree/blob/main/frontend/app/CommonLanguages.tsx"
click node_language_families "https://github.com/devmantowhid/langtree/blob/main/frontend/app/LanguageFamilies.tsx"
click node_api_server "https://github.com/devmantowhid/langtree/blob/main/backend/server.js"
click node_language_routes "https://github.com/devmantowhid/langtree/blob/main/backend/routes/languageRoutes.js"
click node_language_controller "https://github.com/devmantowhid/langtree/blob/main/backend/controllers/languageController.js"
click node_error_handler "https://github.com/devmantowhid/langtree/blob/main/backend/middlewares/errorHandler.js"
click node_firebase_config "https://github.com/devmantowhid/langtree/blob/main/backend/config/firebase-config.js"
click node_ancestry_chain "https://github.com/devmantowhid/langtree/blob/main/backend/utils/create_ancestry_chain.js"
click node_seed_language "https://github.com/devmantowhid/langtree/blob/main/backend/utils/seedLanguage.js"
click node_seed_data "https://github.com/devmantowhid/langtree/blob/main/backend/utils/seed_Data.js"
click node_test_connection "https://github.com/devmantowhid/langtree/blob/main/backend/test-connection.js"

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_root_pkg toneBlue
class node_ui_shell,node_home_page,node_catchall_route,node_common_langs,node_language_families toneAmber
class node_api_server,node_language_routes,node_language_controller,node_error_handler,node_firebase_config,node_ancestry_chain,node_seed_language,node_seed_data,node_test_connection toneMint
```

## Components

### Monorepo

Workspace coordinating frontend and backend packages.

- [Root package](https://github.com/devmantowhid/langtree/blob/main/package.json): workspace · Coordinates installs and workspace-level scripts. · `package.json`

### Frontend

Next.js UI for browsing language trees.

- [App shell](https://github.com/devmantowhid/langtree/blob/main/frontend/app/layout.tsx): next shell · Global layout and styling for the frontend app. · `frontend/app/layout.tsx`
- [Landing page](https://github.com/devmantowhid/langtree/blob/main/frontend/app/page.tsx): next page · Top-level entry page for the language browser. · `frontend/app/page.tsx`
- [Tree route](https://github.com/devmantowhid/langtree/blob/main/frontend/app/[...slug]/page.tsx): catch-all page · Hierarchical route that renders deep language ancestry paths. · `frontend/app/[...slug]/page.tsx`
- [Common langs](https://github.com/devmantowhid/langtree/blob/main/frontend/app/CommonLanguages.tsx): ui component · Reusable browsing component for common languages. · `frontend/app/CommonLanguages.tsx`
- [Families view](https://github.com/devmantowhid/langtree/blob/main/frontend/app/LanguageFamilies.tsx): ui component · Reusable component for language-family navigation and display. · `frontend/app/LanguageFamilies.tsx`

### Backend

Express API and Firebase integration for language data.

- [API server](https://github.com/devmantowhid/langtree/blob/main/backend/server.js): express entrypoint · Node/Express application bootstrap and HTTP listener. · `backend/server.js`
- [Language routes](https://github.com/devmantowhid/langtree/blob/main/backend/routes/languageRoutes.js): api routes · REST surface for language lookup and tree requests. · `backend/routes/languageRoutes.js`
- [Language controller](https://github.com/devmantowhid/langtree/blob/main/backend/controllers/languageController.js): request handlers · Implements API logic for language and ancestry responses. · `backend/controllers/languageController.js`
- [Error handler](https://github.com/devmantowhid/langtree/blob/main/backend/middlewares/errorHandler.js): middleware · Centralized API error formatting and response behavior. · `backend/middlewares/errorHandler.js`
- [Firebase config](https://github.com/devmantowhid/langtree/blob/main/backend/config/firebase-config.js): firestore client · Configures the backend connection to Firebase Firestore. · `backend/config/firebase-config.js`
- [Ancestry chain](https://github.com/devmantowhid/langtree/blob/main/backend/utils/create_ancestry_chain.js): path utility · Reconstructs or validates ordered ancestor chains for routes. · `backend/utils/create_ancestry_chain.js`
- [Seed language](https://github.com/devmantowhid/langtree/blob/main/backend/utils/seedLanguage.js): bootstrap script · Populates Firestore with curated language records. · `backend/utils/seedLanguage.js`
- [Seed data](https://github.com/devmantowhid/langtree/blob/main/backend/utils/seed_Data.js): bootstrap script · Bulk data ingestion for the language tree dataset. · `backend/utils/seed_Data.js`
- [Connection test](https://github.com/devmantowhid/langtree/blob/main/backend/test-connection.js): ops script · Verifies backend connectivity to Firestore. · `backend/test-connection.js`

## Connections

- Root package → App shell: workspace · Coordinates the frontend package and its scripts.
- Root package → API server: workspace · Coordinates the backend package and its scripts.
- App shell → Landing page: renders · Provides the global shell around the landing page.
- App shell → Tree route: wraps · Provides shared layout for deep route pages.
- Landing page → Common langs: uses · Landing page reuses common browsing components.
- Landing page → Families view: uses · Landing page surfaces family-oriented navigation.
- Tree route → Families view: uses · Hierarchical routes render family/navigation views.
- Tree route → Language controller: fetches · Requests language and ancestry data from the API.
- API server → Language routes: mounts · Registers the REST language surface.
- Language routes → Language controller: delegates · Routes forward request handling to controllers.
- Language controller → Firebase config: queries · Uses Firestore connection for persistence reads/writes.
- Language controller → Ancestry chain: reconstructs · Builds ordered ancestor paths for requested languages.
- Language controller → Error handler: fails through · API errors are normalized by centralized middleware.
- Ancestry chain → Firebase config: reads · Resolves ancestry using persisted tree records.
- Seed language → Firebase config: writes · Seeds Firestore with curated language entries.
- Seed data → Firebase config: writes · Bulk loads language tree data into Firestore.
- Connection test → Firebase config: verifies · Checks that the backend can reach Firestore.
- Language routes → Error handler: returns · Route-level failures are formatted consistently.
- Tree route → Ancestry chain: depends on · Deep URLs rely on backend-derived ancestry order.