# Ukrainian London Hub

<https://github.com/Langoner-1/AIDevCamp2026_project/tree/main#ukrainian-london-hub->

<figure><img src="/files/oyaqEiO353edEKNWelMS" alt=""><figcaption></figcaption></figure>

### 🚀 Key Features

* **Interactive Community Map**: A custom-styled map powered by Leaflet.js to help users find Ukrainian landmarks, cafes, and essential services near them.
* **Community Directory**: A curated list of Ukrainian businesses and shops, filterable by category.
* **Cultural Event Board**: Stay updated with concerts, meetups, and cultural celebrations.
* **Job Board**: A dedicated space for job listings within and for the community.
* **AI Chat Agent**: An intelligent community assistant that can answer questions about local services, events, and community resources.
* **Bilingual Interface**: Seamless switching between English and Ukrainian languages.
* **Admin Dashboard**: A secure portal for community moderators to manage listings and data.
* **Modern UI/UX**: A premium design aesthetic using Glassmorphism, smooth animations, and a responsive layout.

### 🛠 Tech Stack

* **Frontend**: Semantic HTML5, Vanilla CSS3 (Custom Variables, Glassmorphism), Modern JavaScript (ES6+).
* **Backend (CMS)**: Node.js with Express.js.
* **AI Agent Service**: Python 3.x, Flask, Google Generative AI (ADK).
* **Map Integration**: Leaflet.js.
* **Data Management**: JSON-based flat-file database for local development and portability.

### 🏁 Getting Started

#### Prerequisites

* [Node.js](https://nodejs.org/) (v14+)
* [Python 3.x](https://www.python.org/)
* A virtual environment is recommended for the AI Agent.

#### Installation

1. **Clone the repository**:

   ```
   git clone <repository-url>
   cd ukrainian-london-hub
   ```
2. **Install CMS Dependencies**:

   ```
   npm install
   ```
3. **Install AI Agent Dependencies**: Navigate to the `london_hub_agent` directory and install the required Python packages:

   ```
   pip install flask flask-cors google-genai python-dotenv
   ```

#### Running the Project

The platform requires two services to be running concurrently:

1. **Start the Web/CMS Server**: In the root of the `ukrainian-london-hub` directory:

   ```
   npm start
   ```

   *The main application will be available at `http://localhost:3000`.*
2. **Start the AI Agent Service**: In the `london_hub_agent` directory:

   ```
   python server.py
   ```

   *The agent service runs on port 5000 and handles the chat intelligence.*

### 🤖 AI Community Assistant

<figure><img src="/files/jEZNFWazndRwRs1eu8NI" alt=""><figcaption></figcaption></figure>

The platform features a sophisticated AI assistant built using the **Google Agent Development Kit (ADK)**. Unlike a simple chatbot, this is a multi-agent system designed to handle diverse community and travel requests.

#### Agent Architecture

<figure><img src="/files/wQZi0qRxRSU6iRS4UmDy" alt=""><figcaption></figcaption></figure>

The assistant uses a **Root Agent** that orchestrates several specialized sub-agents:

* **Community Specialist**: Integrated directly with the project's local database (`shops.json`, `events.json`) via custom tools to provide real-time information about Ukrainian businesses and cultural activities.
* **Flight Specialist**: Handles complex flight search and booking inquiries.
* **Stay Specialist**: Assists in finding Airbnb and local accommodation options.
* **Itinerary Specialist**: Generates personalized trip plans and schedules.

#### Key Intelligence Features

* **Context-Aware Tooling**: The agent can search the community directory using semantic queries to find specific products (like "Korivka") or services (like "Ukrainian-speaking barbers").
* **Multilingual Native Support**: Automatically detects and responds in the user's preferred language (Ukrainian, English, or Russian) while maintaining cultural nuance.
* **Delegation Logic**: The Root agent intelligently routes complex travel requests to the appropriate specialist sub-agent, ensuring expert-level responses for every domain.
* **Memory & Sessions**: Built-in session management allows for continuous, context-rich conversations.\*

### ⚙️ Configuration

#### AI Agent Environment

The AI agent requires a Google API Key to function. Create a `.env` file in the `london_hub_agent` directory:

```
GOOGLE_API_KEY=your_api_key_here
GOOGLE_GENAI_USE_VERTEXAI=0
```

#### CMS Server

The CMS server uses `axios` to communicate with the AI agent. The default proxy endpoint is configured to `http://127.0.0.1:5000/chat`. Ensure both servers are running for the chat feature to work.

### 🔗 Technical Integration

<figure><img src="/files/UPaVey4y7uv1vnIUa5sx" alt=""><figcaption></figcaption></figure>

#### The "Bridge" Architecture

The project uses a proxy pattern to bridge the Node.js frontend with the Python AI service:

1. **Frontend**: Sends a JSON request to the Node.js `/api/chat` endpoint.
2. **Node.js (CMS)**: Acts as a middleware, forwarding the request to the Python Flask server.
3. **Python (Agent)**: Processes the request using the ADK Runner, invokes necessary tools (like the community directory search), and returns the generated content.
4. **Formatting**: The frontend `script.js` parses the markdown-like response from the agent and renders it with custom styles (including our new compact spacing logic).

### 📁 Project Structure

* `index.html`: The primary entry point and landing page.
* `cms-server.js`: The Node.js backend handling APIs for data management and chat proxying.
* `script.js`: Core frontend logic, including language state, search, and chat UI.
* `style.css`: The central stylesheet containing the design system and theme tokens.
* `data/`: Contains JSON files (`events.json`, `shops.json`, etc.) acting as the project's database.
* `admin.html`: The administrative interface for managing community content.

### 📜 License

This project is licensed under the ISC License.

<div><figure><img src="/files/UPaVey4y7uv1vnIUa5sx" alt=""><figcaption></figcaption></figure> <figure><img src="/files/48O45O8rBvFkLWVSZZFn" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/d80qfsJEXkRDYr9Ra1Bg" alt=""><figcaption></figcaption></figure> <figure><img src="/files/tGPCoYgO3SLRidxe3yYt" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wtech-1.gitbook.io/ai-dev-project/ukrainian-london-hub.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.