# TonyBot - Requirements Specification **Status:** Draft 0.2 **Date:** 2026-09-12 **Product:** Chatbot for tonymitsev.com Every substantive change to this document must increment its draft version and be recorded in the change log. ## 1. Purpose TonyBot is a small chatbot that helps visitors navigate the website and learn more about Anton Mitsev, his projects, articles, and contact options. The first version must be useful and complete without requiring an external AI provider. The architecture should allow AI-powered responses to be added later. ## 2. Problem The website content is distributed across many pages. Visitors currently have to find the right page themselves to learn who the author is, what he has built, or how to get in touch with him. ## 3. MVP goals - Answer common questions about the website and its author. - Help visitors find a relevant page, CV, or contact information through a natural-language question. - Support Bulgarian and English. - Have a distinctive, slightly personal tone without misleading visitors. - Make respectful, elegant responses to rude language and insults a visible TonyBot USP from the MVP onward. - Integrate with the existing PHP website without coupling the chatbot to its codebase. ## 4. Out of scope for the MVP - Free-form responses generated by an AI model. - Persistent conversation history between visits. - User accounts or an administration panel. - Personal, medical, legal, or financial advice. - Sending messages on behalf of Anton. - Voice interaction. ## 5. Architecture and deployment ### ARCH-01 - Full decoupling TonyBot must be developed and deployable as a standalone application, preferably in its own project or repository. It must not depend on: - PHP includes or shared PHP classes; - the website's PHP session; - the website's database; - server-side execution inside the website request lifecycle. The website integration must be limited to a static frontend widget and configuration. The website must communicate with the chatbot through a documented HTTPS API. ### ARCH-02 - Node.js backend The chatbot backend must run on Node.js using a currently supported Node.js LTS release. It must expose a small JSON HTTP API for submitting questions and receiving responses. The backend must be independently startable, testable, and deployable without starting the PHP website. ### ARCH-03 - Shared-hosting deployment The preferred first deployment target is the existing shared server, if it provides all of the following: - Node.js LTS support; - a supported way to keep the Node.js process running, such as cPanel Application Manager, Passenger, or an equivalent process manager; - an HTTPS endpoint or subdomain for the API; - environment-variable configuration; - outbound access to any services required by a future AI fallback. The chatbot must not require shared hosting support that is unavailable. If the server cannot reliably run a Node.js process, the cloud deployment option must be used. ### ARCH-04 - Cloud deployment fallback The backend must also be deployable to a managed cloud Node.js service, serverless platform, or small container service. The implementation must remain provider-agnostic. The cloud deployment should use a dedicated API hostname, for example `bot.tonymitsev.com`, with TLS enabled and CORS restricted to the website origins. ### ARCH-05 - Operational independence The website must remain usable when the chatbot backend is stopped, unavailable, or being redeployed. The frontend must fail gracefully and must not prevent the rest of the page from loading. ## 6. Users ### Visitor Wants to quickly understand what the website contains, who Anton is, what projects he has worked on, and where to find specific information. ### Author / administrator Wants to add and edit knowledge and responses without changing the chatbot's processing logic. ## 7. Core user stories - As a visitor, I want to ask "Who is Anton Mitsev?" so that I can get a short introduction. - As a visitor, I want to ask "Where is the CV?" so that I can get a direct link to the CV file. - As a visitor, I want to ask "What projects are available?" so that I can see relevant portfolio pages or projects. - As a visitor, I want to ask questions in English so that I can use the website in my preferred language. - As a visitor, I want a useful response even when my question is unknown, instead of an empty result or a technical error. - As a visitor, I want TonyBot to remain calm and gentlemanly when I use rude language or insult it. - As an administrator, I want to edit responses and links in a separate data structure. ## 8. Functional requirements ### FR-01 - Chat interface The website must provide a visible way to open the chatbot from the main pages. The interface must contain: - a question input field; - a send button; - visually distinct visitor and bot messages; - a welcome message; - a processing indicator; - an error or no-result message. ### FR-02 - Question submission Visitors must be able to submit a question using the send button and the `Enter` key. Empty questions must not be submitted. ### FR-03 - Intent recognition The MVP must recognize at least the following intents: - author introduction; - CV; - contact; - portfolio and projects; - blog and news; - technologies and web development; - website language; - help and example questions. Recognition may be implemented using keywords, text normalization, and synonyms. ### FR-04 - Responses Each supported question must return: - a short text response; - one or more website links when relevant; - the language of the question or the current interface language. Responses must be based only on supported content. The chatbot must not invent facts about the author, projects, or contact details. ### FR-05 - Unknown questions When no match is found, the chatbot must clearly state that it does not recognize the question and suggest example questions or a link to the homepage. ### FR-06 - Bilingual support The MVP must support Bulgarian and English. The language may be selected from the page language. For mixed-language or ambiguous questions, the current interface language should be used. ### FR-07 - Knowledge configuration Texts, keywords, intents, and URLs must be separated from the processing logic so they can be edited without changing the algorithm. ### FR-08 - Abuse prevention The system must apply a basic request-rate limit and a reasonable maximum question length. ### FR-09 - API contract The backend must document at least: - the question endpoint and HTTP method; - request and response JSON shapes; - validation and error responses; - the supported language field; - CORS behavior; - a health-check endpoint. The API must return machine-readable errors and must not expose internal stack traces to visitors. ### FR-10 - Respectful handling of rude language and insults Recognizing and handling rude language is a core MVP feature and a defining TonyBot USP, not a later personality enhancement. The MVP must: - detect common Bulgarian and English profanity, insults, and aggressively phrased messages, including basic punctuation and casing variations; - respond in the current interface language, or in the detected language when it is unambiguous; - remain calm, concise, polite, and gentlemanly, with light elegance or gentle humour where appropriate; - avoid mirroring the user's insult, using profanity in return, shaming the user, threatening the user, or escalating the exchange; - invite the visitor to rephrase the question respectfully and, when a legitimate website question can still be identified, answer that question where practical; - use a configured response set separate from the recognition logic so the tone can be edited without changing the classifier; - treat threats, hate speech, sexual abuse, or requests for harm as safety-sensitive inputs and respond with a brief boundary-setting message without engaging in the abusive content. The bot must not claim to feel hurt, angry, or personally attacked. It may use a recognizable voice, but it must remain transparent that it is a website chatbot. ## 9. MVP content sources The initial knowledge base must contain only verified website content: - homepage; - About page; - contact page; - CV; - portfolio; - web-tech articles; - news and RSS; - redesign page. Contact details and external URLs must be maintained in one place to prevent inconsistencies with the rest of the website. ## 10. Non-functional requirements - Work on desktop and mobile. - Do not block page loading. - Do not require a database for the MVP. - Do not require a permanently running Docker container for the production website or the chatbot backend. - Do not require any PHP code change beyond the static widget integration. - The backend must run locally with a documented Node.js command. - The backend must be deployable both to qualifying shared hosting and to a managed cloud service. - Configuration and secrets must be provided through environment variables, never committed to the repository. - The production API must use HTTPS and allow requests only from configured website origins. - Render a response within one second for local processing under normal conditions. - Produce no JavaScript errors when the chatbot endpoint is unavailable or disabled. - Escape HTML output safely; visitor text must not be interpreted as HTML. - Do not store visitor questions by default. - Provide a health-check endpoint suitable for hosting and monitoring services. ## 11. MVP acceptance criteria The MVP is complete when: 1. The chatbot is available from the homepage without breaking existing navigation. 2. At least ten predefined questions work in Bulgarian and their English equivalents work as well. 3. Questions about the CV, contacts, and portfolio return working links. 4. An unknown question returns a meaningful fallback response. 5. Empty and excessively long questions are handled safely. 6. The interface is usable on a small screen. 7. The backend can be started locally with Node.js independently of the PHP website. 8. The frontend communicates with the backend only through the documented HTTPS API. 9. The backend is successfully deployed either on the shared server or on the selected cloud platform. 10. When the endpoint is stopped, the website remains usable and displays an understandable message. 11. CORS, rate limiting, validation, and health checks are verified in the deployed environment. 12. A representative test set of Bulgarian and English profanity, insults, casing, and punctuation variations is recognized and receives a courteous response in the correct language. 13. The rude-language response does not repeat the insult or contain retaliatory, humiliating, threatening, or profane language. ## 12. Proposed evolution ### Version 0.1 - FAQ bot Static knowledge, keyword matching, two languages, and links to website content. ### Version 0.2 - Content search Extract text from selected pages and show the most relevant results. ### Version 0.3 - AI fallback Use an external AI model only when local matching cannot find a good answer. The model receives limited context from the website. ### Version 1.0 - Personality and analytics Add "Professional", "Web-tech", and "Ironic" modes, opt-in anonymous statistics, and an interface for editing the knowledge base. ## 13. Open decisions - Should the chatbot widget appear on every page or only on the main pages? - Should the first version be Bulgarian-first or treat both languages equally? - What should the exact tone be: professional, friendly, ironic, or a combination? - Should the knowledge base use JSON files, Markdown files, or a small Node.js module? - Does the current shared server satisfy the Node.js process, HTTPS, and process-management requirements? - Which managed cloud platform should be the fallback deployment target? - Should the future AI fallback run in the same Node.js service or as a separate service? ## 14. Change log ### Draft 0.2 - 2026-09-12 - Added respectful handling of Bulgarian and English rude language, profanity, and insults as an MVP functional requirement. - Defined the elegant, gentlemanly response style and explicit non-escalation boundaries. - Added bilingual rude-language user story and MVP acceptance criteria. - Added the rule that every substantive requirements change increments the document version and is recorded here. ## License Copyright (c) 2026 Anton Mitsev Permission is hereby granted, free of charge, to any person obtaining a copy of this document and associated documentation files (the "Document"), to deal in the Document without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Document, and to permit persons to whom the Document is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Document. THE DOCUMENT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE DOCUMENT OR THE USE OR OTHER DEALINGS IN THE DOCUMENT. --- This document was generated with Codex.