DEV Community

Anthony Leignel
Anthony Leignel

Posted on Edited on

🤖 Local Flask Chatbot Architecture: From a Conversational API to Three Independent Workspaces

Local Flask assistant running three independent conversations

A chatbot does not necessarily require an artificial intelligence model, a remote database, or complex infrastructure to address practical needs. A Python architecture built with Flask, a local knowledge base, and a web interface can provide a sufficient foundation for a standalone conversational assistant.

This article explores that architecture and its evolution into a local assistant organized around three independent conversational workspaces.


1. The Base Architecture

The chatbot is built around a separation between the HTTP server, conversational logic, data, and user interface.

This organization allows the internal behavior of the chatbot to evolve without rebuilding its interface. It also makes it possible to replace the knowledge base or integrate an external response engine.

The initial project structure is as follows:

chatbot-flask/
│
├── app.py
├── main.py
├── passenger_wsgi.py
├── requirements.txt
├── .env.example
├── index.html
│
├── sample_data/
│   └── sample_data.json
│
└── docs/
    ├── INSTALL.md
    └── README.md
Enter fullscreen mode Exit fullscreen mode

The app.py file serves as the entry point for the Flask server. It exposes HTTP routes, receives client requests, and forwards questions to the conversational logic.

The main.py file handles question processing and response generation using local data or, when enabled, the OpenAI API.

The index.html interface uses HTML and vanilla JavaScript to communicate with the server. It does not rely on a front-end framework.

Finally, sample_data.json contains the knowledge base used by the chatbot in its local mode.



2. Communication Between the Interface and the Server

The user interface and the conversational engine communicate through an HTTP API.

The server exposes two main endpoints:

Method Route Purpose
GET / Checks whether the API is running
POST /chat Sends a question to the chatbot

A user interface is also available through the /ui route.

A question is sent to the server as a JSON request:

{
  "question": "Hello"
}
Enter fullscreen mode Exit fullscreen mode

The server forwards the question to the conversational logic, retrieves the response, and returns it to the client in JSON format.

The general request flow can be represented as follows:

HTML / JavaScript Interface
            │
            ▼
      POST /chat
            │
            ▼
      Flask Server
         app.py
            │
            ▼
   Conversational Logic
         main.py
            │
            ▼
   JSON Data or OpenAI
            │
            ▼
      JSON Response
Enter fullscreen mode Exit fullscreen mode

This separation allows the same server to support different interfaces, whether a web page, a local application, or another client capable of making HTTP requests.



3. A Knowledge Base Without a Database Server

In its local configuration, the chatbot uses a JSON file to store its knowledge base.

This approach avoids introducing a SQL server or a vector database when the volume of data and functional requirements do not justify one.

The file can be edited directly, backed up, or versioned with Git. Its data structure remains accessible and independent of any external service.

However, this approach has limitations. A JSON file becomes less suitable as the volume of data grows significantly, when multiple processes need to perform concurrent writes, or when complex queries are required.

For a moderately sized knowledge base, it remains a straightforward solution to maintain.



4. A Response Engine With or Without Artificial Intelligence

OpenAI integration is optional. The chatbot can operate without an Internet connection by relying exclusively on its local knowledge base.

The external service is enabled through an environment variable:

OPENAI_API_KEY=your_api_key
Enter fullscreen mode Exit fullscreen mode

The API key is stored in a .env file and should never be embedded directly in the source code.

When OpenAI access is available and configured, the chatbot can use the service to generate responses. Otherwise, it continues operating using local JSON data.

         User Question
                │
                ▼
      Conversational Engine
                │
       ┌────────┴────────┐
       ▼                 ▼
   Local Mode       OpenAI Mode
   JSON File        Remote API
       │                 │
       └────────┬────────┘
                ▼
             Response
Enter fullscreen mode Exit fullscreen mode

An important distinction must be made between running an application locally and processing its data locally. When the OpenAI API is enabled, the information required for the request is transmitted to a remote service.

Fully offline operation therefore corresponds to the mode that relies exclusively on local data.



5. Extending the Chatbot Into Multiple Conversational Workspaces

A single conversational interface becomes less practical when several categories of information need to be accessed simultaneously.

In a development environment, a conversation may contain general project information, implementation details, technical configurations, or working notes. Combining all these elements within a single history makes it harder to maintain separate contexts.

The assistant builds on the original Flask chatbot and extends its interface into three distinct conversational workspaces.

Each workspace serves a specific purpose:

  • Overview: general information and project summaries
  • Technical: configurations, documentation, and technical information
  • Memory: notes, meetings, and reminders

The overall organization becomes:

┌────────────┐ ┌────────────┐ ┌────────────┐
│  Overview  │ │ Technical  │ │   Memory   │
│            │ │            │ │            │
│ Independent│ │ Independent│ │ Independent│
│   history  │ │   history  │ │   history  │
└────────────┘ └────────────┘ └────────────┘
Enter fullscreen mode Exit fullscreen mode

The objective is not to introduce multiple artificial intelligence models, but to separate use cases and conversation histories.

All three workspaces remain accessible simultaneously. A technical question can therefore be handled without interrupting access to general project information or a conversation dedicated to working notes.



6. Separating the Interface Is Not Enough to Isolate Conversations

In a multi-conversation architecture, visually separating the windows does not, by itself, guarantee context isolation.

Each conversation must maintain its own history. If all windows send messages to a shared state without distinction, the server may mix information despite the separation at the interface level.

One possible implementation is to associate an identifier with each conversation:

{
  "conversation_id": "technical",
  "question": "What are the configuration parameters?"
}
Enter fullscreen mode Exit fullscreen mode

The server can then use this identifier to select the appropriate conversation history before processing the question.

This organization allows a shared conversational engine to operate with separate conversation states.

This is an example of a design pattern applicable to a multi-conversation Flask architecture, rather than an excerpt from the current implementation. Separation can also be achieved by running multiple independent chatbot instances.

In both cases, the underlying principle remains the same: each conversation must preserve its own context without modifying the context of the others.



7. Local Execution and Deployment

The base chatbot can run with Python 3.10 or later.

After creating a virtual environment, the dependencies are installed from the requirements.txt file.

python -m venv venv
Enter fullscreen mode Exit fullscreen mode

On Windows:

.\venv\Scripts\Activate.ps1
Enter fullscreen mode Exit fullscreen mode

On Linux or macOS:

source venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

The dependencies can then be installed and the server started:

pip install -r requirements.txt
python app.py
Enter fullscreen mode Exit fullscreen mode

The interface is available at:

http://localhost:5000/ui
Enter fullscreen mode Exit fullscreen mode

The architecture also supports deployment on shared hosting environments compatible with Passenger and WSGI. The passenger_wsgi.py file provides the entry point required for this deployment mode.

In its local three-workspace configuration, the assistant can remain available in the background and launch when the operating system starts.

Remote deployment, however, requires additional precautions, particularly regarding authentication, data access, CORS configuration, and API key protection.



Conclusion

The transition from a Flask chatbot to a multi-conversation interface illustrates the value of separating application components from the initial design stage.

The HTTP server, response logic, data, and user interface can evolve independently. An architecture originally designed for a single conversation can therefore become the foundation for an assistant organized around multiple use cases.

The main challenge is not necessarily response generation, but the management of contexts, conversation histories, and the data associated with each workspace.

This approach makes it possible to build specialized assistants without automatically introducing complex infrastructure or a dependency on a remote artificial intelligence service.


Technical Documentation

GitHub repository: architecture and installation documentation


https://palks-studio.com

Top comments (0)