Client Support Platform Software Architecture & Feature Specification Document type: System Architecture and Functional Requirements Project: AI-Powered Client Support Portal Version: 1.0 Status: Proposed Architecture --- 1. Project Overview The Client Support Platform is a centralized support website where clients can access their website credentials, view website-specific user manuals, ask questions about website functionality, and report technical problems. Each client website will be registered and bound to a dedicated client profile. The company's administrators will upload the corresponding user manual, configure the website details, and manage the client's access. When a client submits a question, the platform will request a screenshot of the relevant page or problem. The AI will receive the client's question, screenshot, and relevant user manual to determine whether the request is a usage-related doubt or a technical issue. - Usage-related doubt: The AI explains how to use the website feature by referencing the client's manual. - Technical issue or bug: The AI collects the relevant details, prepares a structured issue report, and forwards it to the company's support team. - Uncertain or high-risk issue: The system escalates the request to a human support agent rather than inventing an answer. The objective is to reduce repetitive support requests while providing every client with accurate, website-specific assistance. 2. System Objectives 1. Maintain a separate profile for every client and their associated websites. 2. Securely deliver website credentials to authorized clients. 3. Store and manage a separate user manual for each website. 4. Provide an AI-powered question-and-answer interface. 5. Analyze screenshots alongside user questions and documentation. 6. Automatically classify requests as usage doubts, technical bugs, or other support requests. 7. Forward technical issues to the appropriate support team with sufficient diagnostic context. 8. Track support tickets, responses, and resolution status. 9. Maintain access controls, audit logs, and tenant-level data isolation. 10. Allow administrators to update manuals, website bindings, and client permissions without rebuilding the platform. 3. System Architecture The platform will use a modular architecture with the following logical components. 3.1 Client Portal The client-facing interface through which customers access their accounts. Features: - Secure login and logout. - Dashboard displaying registered websites. - Website details and credential access. - Website-specific user manual. - AI support chat. - Screenshot upload and preview. - Conversation history. - Support ticket tracking. - Notifications when the support team responds. - Access to previously resolved issues and answers. 3.2 Authentication and Client Management Responsible for identifying the client and determining which resources they can access. Responsibilities: - Account creation and invitation. - Secure password hashing and authentication. - Session management. - Password reset and account recovery. - Role-based access control. - Mapping users to client organizations and websites. - Enforcing tenant isolation on every protected request. A client must never be able to access another client's website credentials, manuals, screenshots, conversations, or tickets by changing a URL or API identifier. 3.3 Website Binding Service This component establishes the relationship between a client, their website, its documentation, and its support configuration. Each website record should include: - Internal website ID. - Client or organization ID. - Website name. - Website URL and environment. - Project or deployment identifier, where applicable. - Website version or release information. - Associated user manual. - Support team assignment. - Website-specific AI configuration. - Active or inactive status. For example, a client may have a company website, an online store, and an admin dashboard. Each should have a separate binding so that the AI retrieves the correct manual for the selected website. Website binding does not automatically provide access to the website's source code. If automated code diagnostics are required, a separate authorized integration with the source repository, deployment logs, or monitoring system must be configured. 3.4 User Manual Management Service The manual service stores the documentation that explains how each website works. Supported documentation may include: - PDF manuals. - Text and Markdown documents. - Screenshots and annotated guides. - Step-by-step feature instructions. - Frequently asked questions. - Feature-specific troubleshooting guides. Each manual should have metadata such as website ID, document version, upload date, and publication status. When a manual is updated, the system should index the new version and ensure future AI responses use the published documentation. 3.5 AI Support Orchestrator This component coordinates the entire AI interaction. It retrieves the correct manual, processes the user's question and screenshot, classifies the request, and decides whether to answer or escalate. The AI orchestrator should not have unrestricted access to all client data. It should receive only the information authorized for the current client, website, and conversation. 3.6 Ticket and Support Team Service Responsible for transferring technical issues from the AI support workflow to the company's human support team. Responsibilities: - Creating tickets. - Assigning tickets to teams or agents. - Attaching screenshots and diagnostic summaries. - Tracking status and priority. - Recording internal notes and client-facing replies. - Sending notifications. - Maintaining a complete resolution history. --- 4. End-to-End User Flow Stage 1: Client onboarding 1. An administrator creates a client account. 2. The administrator registers the website or websites developed for that client. 3. Each website is bound to the appropriate client profile. 4. The administrator uploads the website's user manual. 5. The system validates and indexes the manual. 6. Website credentials are provisioned through a secure credential-delivery mechanism. 7. The client receives an invitation and logs into the support portal. Result: The client can access only their assigned websites, credentials, manuals, and support conversations. Stage 2: Client selects a website 1. The client opens the support portal. 2. The dashboard displays the websites associated with their account. 3. The client selects the website they need help with. 4. The system loads the website's details, published manual, and support history. 5. The client opens the AI support chat. The selected website ID becomes part of the authenticated support context. The backend must validate it against the client's permissions instead of trusting a website ID supplied by the browser. Stage 3: Client submits a question 1. The client enters a question describing their doubt or issue. 2. The portal asks the client to attach a screenshot of the relevant page, error, or unexpected behavior. 3. The client uploads the screenshot and submits the request. 4. The backend validates the request and stores the screenshot securely. 5. The AI orchestrator retrieves the relevant manual sections and supporting documentation. 6. The system prepares the AI input. The AI input contains: - The client's question. - The selected website's authorized context. - The screenshot, when provided. - Relevant user manual sections. - Known website version or release information, if available. - Relevant previous messages from the same conversation. Screenshots may contain sensitive information. The portal should warn users to hide passwords, payment information, personal information, and secret keys before uploading. Stage 4: AI analysis and classification The AI evaluates the request and determines its likely category. Category| Example| Action Usage doubt| "How do I add a new product?"| Explain using the manual Navigation help| "Where can I find the order history?"| Give step-by-step directions Suspected bug| "The save button does not work."| Create a technical support ticket Error or crash| "The dashboard displays a server error."| Escalate with screenshot and details Missing documentation| "The manual does not explain this setting."| Ask for clarification or escalate Uncertain diagnosis| The screenshot and description are insufficient| Request more information or human review The AI must distinguish between a confirmed bug and a suspected bug. A screenshot alone may not establish the underlying cause. Stage 5A: Usage doubt resolution When the request is a documentation-related question: 1. The AI retrieves the relevant manual sections. 2. It checks whether the documentation answers the question. 3. It generates a concise, step-by-step explanation. 4. It references the relevant manual section or page, where possible. 5. It asks whether the instructions resolved the problem. Example: Client: "How do I change the homepage banner?" AI response: 1. Log in to your website's administration dashboard. 2. Open the Homepage or Banner Management section. 3. Select the banner you want to update. 4. Upload the replacement image and enter the required details. 5. Save your changes and open the public homepage to verify the result. The exact instructions must be retrieved from that client's published manual. This example is illustrative. If the instructions do not resolve the issue, the client can request further help or convert the conversation into a support ticket. Stage 5B: Technical issue escalation When the request appears to involve a website bug, code defect, server problem, or other technical failure: 1. The AI summarizes the problem. 2. It identifies the relevant website and affected feature. 3. It extracts visible error messages from the screenshot where possible. 4. It asks for missing information when necessary. 5. It creates a structured support ticket. 6. It attaches the original screenshot and relevant conversation context. 7. It assigns the ticket according to the support team's routing rules. 8. It informs the client that the issue has been submitted. 9. The support team investigates the problem and responds through the portal. The AI should not claim that source code is defective or that a fix has been applied unless the relevant evidence or authorized action confirms it. Stage 6: Human support and resolution 1. A support agent opens the ticket in the staff dashboard. 2. The agent reviews the question, screenshot, manual references, AI summary, and any available diagnostic information. 3. The agent requests additional information if required. 4. The agent investigates the issue and applies or coordinates the fix. 5. The agent records the resolution and replies to the client. 6. The client receives a notification and can view the response. 7. The ticket is marked resolved after the appropriate confirmation or resolution procedure. The original AI conversation and ticket history remain linked for future reference. --- 5. AI Processing Pipeline The recommended pipeline is: Authentication → Website authorization → Screenshot validation → Manual retrieval → AI analysis → Request classification → Answer or ticket escalation 5.1 Manual retrieval using RAG Implement Retrieval-Augmented Generation (RAG) rather than sending the entire manual to the AI for every request. The process: 1. Extract text from the uploaded manual. 2. Split the content into searchable sections or chunks. 3. Store the text, metadata, and embeddings in a searchable index. 4. Associate every chunk with its client, website, and document version. 5. When a question arrives, search only the authorized website's documentation. 6. Send the most relevant sections to the AI with the question and screenshot. 7. Generate an answer grounded in those sources. This reduces unnecessary token usage and improves relevance for large manuals. If relevant documentation cannot be found, the AI must state that the manual does not provide enough information rather than inventing instructions. 5.2 Screenshot analysis A vision-capable AI model can analyze uploaded screenshots to identify: - Visible error messages. - Missing or incorrectly displayed UI elements. - Unexpected layouts. - Relevant buttons, menus, and form fields. - The apparent location of a user-reported problem. Screenshot analysis cannot reliably identify every backend or database defect. When more evidence is required, the system should request browser console errors, request IDs, timestamps, or authorized server logs. 5.3 Structured AI output The AI should return a structured result that the backend validates before taking action. Recommended fields: - "category": usage_doubt, suspected_bug, technical_issue, other, or uncertain. - "summary": brief description of the request. - "manual_references": relevant document sections. - "answer": client-facing explanation, if appropriate. - "missing_information": questions that must be asked. - "suggested_priority": proposed ticket priority. - "escalation_reason": why human intervention is required. The backend, not the model alone, decides whether to create a ticket, which client can access it, and which support team receives it. --- 6. Functional Feature Specification 6.1 Client features - Secure client login. - Multiple websites per client account. - Website dashboard. - Secure credential viewing and delivery. - Downloadable or browser-readable user manuals. - AI chat with website context. - Screenshot upload. - Conversation history. - Manual references in AI answers. - Follow-up questions. - Convert unresolved questions into support tickets. - Ticket status and priority visibility. - Human support replies. - Notifications for ticket updates. - Resolved issue history. 6.2 Administrator features - Create, edit, suspend, and manage client accounts. - Register and bind websites. - Assign websites to clients. - Provision and rotate website credentials. - Upload, publish, replace, and archive manuals. - Manage manual versions. - Configure AI model and support policies. - Assign support teams. - Search client and ticket records according to permissions. - Review AI escalations. - Monitor ticket resolution time and support workload. - View audit logs. - Configure retention policies and access permissions. 6.3 Support agent features - Staff login with role-based permissions. - Central ticket inbox. - Filters by client, website, status, priority, and assignment. - Screenshot and attachment preview. - AI-generated problem summary. - Relevant manual references. - Conversation transcript. - Internal notes. - Request additional details. - Assign and reassign tickets. - Update status and priority. - Reply to clients. - Record root cause and resolution. - Track response and resolution times. 6.4 Optional advanced features - Email notifications. - In-portal notification center. - Automatic ticket categorization and routing. - Repeated-issue detection. - Searchable knowledge base built from approved resolutions. - Website health checks. - Authorized integration with Git repositories and deployment logs. - Version-aware documentation. - Client satisfaction feedback. - AI usage limits and cost monitoring. - SLA tracking and reporting. --- 7. Proposed Technical Architecture The implementation can use a conventional web application architecture. Layer| Recommended technology| Responsibility Frontend| HTML, CSS, JavaScript or React| Client portal and staff dashboard Backend API| PHP with Laravel, or Node.js| Authentication, authorization, business logic Relational database| MySQL or PostgreSQL| Clients, websites, manuals, tickets, conversations File storage| Private object storage or private server storage| Screenshots, manuals, attachments AI integration| Vision-capable LLM API| Question answering and screenshot analysis Search and retrieval| Full-text search plus vector search| Manual retrieval Background jobs| Redis-backed queue or equivalent| Manual processing, notifications, AI tasks Notifications| Email service and in-app notifications| Client and agent updates Monitoring| Application logs and error monitoring| Reliability and diagnostics For a PHP-based deployment, Laravel, MySQL, private file storage, a queue worker, and an AI API integration would be a practical starting point. A dedicated vector database is not mandatory for the first version. A suitable relational database with full-text search, or a database extension supporting vector search, can be sufficient initially. The architecture should remain modular so that AI providers, storage systems, and search implementations can be changed later. --- 8. Database Design The following is the proposed logical schema. It is not a final SQL migration. 8.1 "organizations" Stores the company or client organization. Fields: - "id" - "name" - "status" - "created_at" - "updated_at" 8.2 "users" Stores client users, administrators, and support agents. Fields: - "id" - "organization_id" — nullable for platform-wide staff, where appropriate - "name" - "email" - "password_hash" - "role" - "status" - "created_at" - "updated_at" Roles should be enforced through permissions, not simply by hiding interface elements. 8.3 "websites" Stores website bindings. Fields: - "id" - "organization_id" - "name" - "website_url" - "environment" - "release_version" - "support_team_id" - "status" - "created_at" - "updated_at" 8.4 "website_credentials" Stores references to protected credential records. Fields: - "id" - "website_id" - "credential_label" - "username_or_login_identifier" - "secret_reference" - "last_rotated_at" - "created_at" - "updated_at" Passwords and API secrets should not be stored in plaintext. Use a dedicated secrets manager or strong authenticated encryption with keys stored separately from the database. User account passwords must be hashed rather than reversibly encrypted. Credential viewing and delivery should be audited. Prefer one-time or expiring delivery links where supported. 8.5 "manuals" Stores manual metadata. Fields: - "id" - "website_id" - "title" - "version" - "storage_key" - "processing_status" - "publication_status" - "uploaded_by" - "created_at" - "published_at" 8.6 "manual_chunks" Stores searchable manual sections. Fields: - "id" - "manual_id" - "website_id" - "chunk_text" - "page_number" - "section_title" - "embedding_reference" - "created_at" The website ID should support authorization filtering during retrieval, and published manual versions should be distinguished from drafts and archived versions. 8.7 "conversations" Stores client support conversations. Fields: - "id" - "organization_id" - "website_id" - "user_id" - "status" - "created_at" - "updated_at" 8.8 "messages" Stores individual messages and AI responses. Fields: - "id" - "conversation_id" - "sender_type" - "message_text" - "message_category" - "ai_model" - "created_at" 8.9 "attachments" Stores metadata for screenshots and other uploaded files. Fields: - "id" - "conversation_id" - "message_id" - "storage_key" - "file_type" - "file_size" - "upload_status" - "created_at" Files should be kept private and served only after authorization checks. 8.10 "support_tickets" Stores escalated issues. Fields: - "id" - "organization_id" - "website_id" - "conversation_id" - "created_by" - "assigned_to" - "category" - "priority" - "title" - "description" - "status" - "resolution_summary" - "created_at" - "updated_at" - "resolved_at" 8.11 "ticket_events" Stores ticket activity history. Fields: - "id" - "ticket_id" - "actor_user_id" - "event_type" - "event_details" - "created_at" 8.12 "notifications" and "audit_logs" Notifications store delivery and read status for client and staff alerts. Audit logs record security-relevant actions such as credential access, manual publication, permission changes, and ticket reassignment. Sensitive secrets should never be written to logs. --- 9. Security and Privacy Requirements Because the platform manages client credentials and potentially sensitive screenshots, security must be a core architectural requirement. Authentication and authorization - Use secure session cookies or an equivalent secure authentication mechanism. - Apply role-based access control. - Verify ownership and website permissions on every API request. - Protect against insecure direct object reference (IDOR) vulnerabilities. - Use CSRF protection where applicable. - Rate-limit login, upload, and AI endpoints. Credential security - Store account passwords using a suitable password hashing algorithm. - Keep website passwords and API keys in a secrets manager or encrypted storage. - Never send credentials to the AI model. - Avoid exposing secrets in URLs, browser logs, support transcripts, or notifications. - Record credential access and rotation events. File security - Validate file types and file sizes. - Verify file content rather than trusting the filename or declared MIME type. - Use randomized storage keys. - Store manuals and screenshots outside the public web root or in private object storage. - Scan uploads where appropriate. - Generate short-lived authorized download links. - Apply retention and deletion policies. AI security - Treat uploaded screenshots, manual contents, and client messages as untrusted input. - Defend against prompt injection contained in documents or screenshots. - Do not allow retrieved documents to override system security policies. - Restrict the AI to the current website's authorized manual. - Validate structured AI output. - Require explicit authorization and server-side checks for any consequential action. - Avoid sending unnecessary personal data or secrets to external AI providers. Privacy and retention - Define how long screenshots, messages, and logs are retained. - Provide an appropriate deletion process. - Limit staff access to client information according to their responsibilities. - Review the AI provider's data-retention and training policies before sending client content. - Maintain appropriate consent, privacy notices, and contractual terms. --- 10. Error Handling and Fallback Behavior The system must provide a clear fallback for each failure scenario. Scenario| Expected behavior Screenshot missing| Prompt the client to attach it, or allow a documented exception Screenshot upload fails| Preserve the question and allow a retry Manual is unavailable| Explain the limitation and route to human support if needed AI service is unavailable| Save the request and offer ticket submission or retry AI cannot determine the answer| Ask a clarifying question or escalate Ticket creation fails| Preserve the request and retry safely without duplicate tickets Unauthorized website access| Deny the request and record the security event Manual indexing fails| Mark the manual as unprocessed and alert an administrator Notification delivery fails| Keep the ticket available in the portal and retry notification delivery The platform should use background jobs, retry limits, idempotency controls, and operational logging to prevent transient failures from losing client requests. --- 11. API Design Outline The backend can expose REST APIs similar to the following. Method| Endpoint| Purpose POST| "/api/auth/login"| Authenticate a user GET| "/api/me"| Retrieve the authenticated profile GET| "/api/websites"| List authorized websites GET| "/api/websites/{id}"| Retrieve an authorized website GET| "/api/websites/{id}/manuals"| List published manuals GET| "/api/manuals/{id}"| Access an authorized manual POST| "/api/conversations"| Create a support conversation POST| "/api/conversations/{id}/messages"| Submit a question and optional attachment GET| "/api/conversations/{id}"| Retrieve conversation history POST| "/api/conversations/{id}/escalate"| Request human support GET| "/api/tickets"| List tickets visible to the current user GET| "/api/tickets/{id}"| Retrieve an authorized ticket POST| "/api/tickets/{id}/replies"| Submit a reply PATCH| "/api/tickets/{id}"| Update permitted ticket fields POST| "/api/admin/websites"| Register a website POST| "/api/admin/websites/{id}/manuals"| Upload a manual POST| "/api/admin/websites/{id}/credentials"| Provision credential records These endpoints are proposed examples, not existing routes. Every endpoint must enforce authentication and authorization on the server. Administrative endpoints must have additional permission checks. Uploads should use a controlled upload workflow, and ticket status transitions should be validated. --- 12. User Interface Structure Client portal Dashboard - Welcome message. - Registered websites. - Quick access to manuals. - Open ticket count. - Recent support activity. Website details - Website name and URL. - Environment and version, if available. - Secure credential access. - Manual library. - Website-specific support chat. AI support - Chat interface. - Screenshot attachment and preview. - Selected website indicator. - AI response with manual references. - Follow-up questions. - Escalation and ticket status. My tickets - Ticket number. - Website. - Issue title. - Priority. - Current status. - Last updated date. - Support replies. Administration dashboard - Client and organization management. - Website binding management. - Credential provisioning. - Manual upload and publication. - AI usage and service health. - Support team management. - Ticket queue and escalation monitoring. - Audit logs and system settings. Support team dashboard - Assigned and unassigned tickets. - Priority-based queue. - Client and website context. - Screenshot viewer. - AI summary and relevant documentation. - Conversation timeline. - Internal notes and client replies. - Resolution and root-cause fields. --- 13. Non-Functional Requirements The platform should also satisfy the following quality requirements. - Isolation: All client data must be tenant-scoped. - Reliability: Failed AI or notification operations must not lose submitted requests. - Performance: Common dashboard and ticket operations should remain responsive under normal load. - Scalability: AI analysis and manual indexing should run asynchronously when needed. - Maintainability: Website configuration, AI logic, ticket management, and manual processing should be separate modules. - Observability: The system should record failures, processing durations, AI usage, and ticket metrics. - Accessibility: The portal should support keyboard navigation, clear error messages, and mobile layouts. - Auditability: Important administrative and support actions should be traceable. - Recoverability: Database backups, file backups, and tested restoration procedures should be maintained. Specific performance targets, availability objectives, and retention periods should be finalized according to expected traffic, hosting capacity, and company policies. --- 14. Implementation Roadmap Phase 1 — Foundation - Authentication and role management. - Client and organization records. - Website registration and binding. - Secure credential management. - Manual upload and publication. - Basic client dashboard. Phase 2 — AI support - Manual text extraction and indexing. - Website-specific manual retrieval. - AI chat integration. - Screenshot upload and vision analysis. - Request classification. - Grounded answers with manual references. Phase 3 — Support ticket workflow - Ticket creation and escalation. - Agent dashboard. - Ticket assignment and status tracking. - Client replies and notifications. - Conversation and ticket history. Phase 4 — Production hardening - Tenant-isolation testing. - Credential and attachment security testing. - AI prompt-injection testing. - Upload validation and abuse prevention. - Monitoring, backups, and recovery. - Rate limits and usage budgets. - User acceptance testing. Phase 5 — Advanced capabilities - Authorized source-code and deployment integrations. - Website version-aware troubleshooting. - Approved knowledge base built from resolved tickets. - SLA reports and operational analytics. - Automated detection of recurring problems. --- 15. Acceptance Criteria The initial release should be considered ready only when the following conditions are met. 1. A client can log in and see only their assigned websites. 2. An administrator can bind a website to the correct client. 3. Each website can have its own published user manual. 4. The AI retrieves documentation from the selected website only. 5. The client can submit a question with a screenshot. 6. The AI can answer documented usage questions with appropriate references. 7. The AI can identify suspected technical issues and prepare structured escalation details. 8. A support agent can view the original question, screenshot, website context, and relevant conversation. 9. A support agent can reply and update ticket status. 10. The client can track the ticket and view the response. 11. Unauthorized cross-client access to websites, manuals, credentials, files, and tickets is prevented. 12. Failed AI requests and ticket operations do not silently discard client submissions. 13. Website credentials are never included in AI prompts or exposed through ordinary logs. 14. Administrators can replace a manual and publish a new version. 15. Audit logs and backup procedures are operational. --- 16. Final Recommendation Build the platform as a multi-tenant client support portal with website-specific AI assistance and human escalation. The recommended initial implementation is a modular PHP/Laravel or Node.js backend, a relational database, private file storage, a manual retrieval pipeline, a vision-capable AI integration, and a dedicated ticket-management interface. The most important architectural decisions are: - Bind every conversation to an authorized client and website. - Retrieve only that website's published documentation. - Use screenshots as supporting diagnostic evidence, not as proof of a backend root cause. - Keep credentials separate from the AI workflow. - Let the backend enforce permissions and ticket actions. - Escalate uncertain or technical problems to human agents. - Preserve the full conversation-to-ticket relationship for traceability. This design provides a practical foundation for delivering client onboarding, documentation-based self-service, AI troubleshooting, and structured technical support through one centralized website. End of document.