Additionally we will add backend folder in monorepo and database schema in monorepo too.
but you can see there are many apps for customized frontend for each. so all of them has different database scheme. how to deal with it. recommend me folder structure

---

# Architectural Decision Records (ADR) for Q-Hub

This document records the architectural decisions made for the Q-Hub platform.

---

## ADR-001: Frontend Framework Selection

**Title:** Frontend Framework Choice is Remix  
**Status:** Decided  
**Date:** 2025-07-05

### Context

The Q-Hub platform is a data-intensive application that requires a robust, performant, and scalable frontend. Key features include real-time dashboards, a flexible report builder, complex data visualizations, and secure user workflows. The architecture must support server-side rendering (SSR) for fast initial page loads and handle complex data fetching and mutations efficiently. The target audience consists of enterprise users who expect a fast, reliable, and desktop-class web experience.

### Decision

We will use **Remix** as the primary frontend framework for building the Q-Hub web application.

### Consequences

**Pros:**

- **Data Loading Model:** Remix's loader/action paradigm aligns perfectly with our need to fetch and mutate data for specific UI components. It simplifies data management and eliminates client-side request waterfalls.
- **Performance:** A focus on web standards and a compiler that optimizes for the server-client interaction leads to faster navigation and a better user experience. Nested routing allows components to load data in parallel.
- **Developer Experience:** The clear separation of concerns between UI components and their data requirements (loaders/actions) can lead to more maintainable and testable code.
- **Error Handling:** Built-in error boundaries (`ErrorBoundary`) at the route level provide a resilient user experience, which is critical for an enterprise analytics platform.

**Cons:**

- **Ecosystem:** While growing, the Remix ecosystem and community may be smaller than that of other frameworks like Next.js, potentially leading to fewer third-party libraries or community-driven solutions.
- **Learning Curve:** The team will need to become proficient in Remix's specific conventions and data-loading patterns.

---

## ADR-002: Backend System Interface

**Title:** Backend Technology is Python (External)  
**Status:** Decided  
**Date:** 2025-07-05

### Context

The platform's vision requires a powerful backend capable of universal data connectivity, real-time data processing, and running complex AI/ML models, including the integration with the Minitab engine. These capabilities are best served by a dedicated backend system.

### Decision

The backend will be a **Python-based system**. The Remix frontend will interact with this backend via a well-defined API (e.g., REST or GraphQL). This ADR acknowledges that the backend's architecture is managed separately and is not part of the frontend monorepo.

### Consequences

**Pros:**

- Python's extensive ecosystem of libraries for data science, machine learning (e.g., Pandas, Scikit-learn), and database connectivity is ideal for our core requirements.
- Clear separation of concerns between the frontend (presentation) and backend (business logic, data processing).

**Cons:**

- Requires careful design and maintenance of the API contract between the Remix frontend and the Python backend to ensure smooth integration.

---

## ADR-003: UI Development and Design System

**Title:** UI Architecture is Atomic Design  
**Status:** Decided  
**Date:** 2025-07-05

### Context

Q-Hub is a complex application with many recurring UI elements across dashboards, forms, reports, and settings pages. To ensure visual consistency, reduce code duplication, and accelerate development, a systematic approach to building UI components is essential.

### Decision

We will adopt the **Atomic Design** methodology for our UI component library. The hierarchy will be structured as follows:

- **Atoms:** The smallest indivisible UI elements (e.g., Button, Input, Label, Icon).
- **Molecules:** Simple combinations of atoms that form a functional unit (e.g., a search form with an input and a button).
- **Organisms:** More complex UI components composed of molecules and/or atoms (e.g., a chart with a title and filters).
- **Templates:** Page-level structures that lay out organisms into a wireframe.
- **Pages:** Concrete instances of templates filled with real content, representing the final UI.

### Consequences

**Pros:**

- **Reusability & Consistency:** Promotes the reuse of components, ensuring a consistent look and feel across the entire platform.
- **Scalability:** Provides a clear methodology for adding new components and features without introducing inconsistencies.
- **Faster Development:** Once the core atoms and molecules are built, assembling new UIs becomes significantly faster.
- **Parallel Work:** Frontend developers can work on building the component library while others work on page structure and data integration.

**Cons:**

- **Initial Overhead:** Requires an upfront investment in planning and building the foundational atom/molecule library.
- **Strict Governance:** The team must be disciplined in adhering to the methodology to prevent the system from becoming disorganized.

---

## ADR-004: Customer Customization Management Strategy – Adopting a Package-based Monorepo

**Title:** Package-based Monorepo for Customer Customization  
**Status:** Decided  
**Date:** 2025-07-07

### Context

Q-Hub must support extensive customer-specific customizations and is deployed on-premise using `docker-compose` for the full stack. Two approaches were considered for managing these customizations:  
- **Branch-based:** Each customer gets a dedicated branch, with code copied and isolated per customer.  
- **Package-based Monorepo:** All code is managed in a single repository, with shared and custom logic separated into packages.

### On-Premise Architecture: Monorepo with Customer-specific Builds

The core of this approach is to develop efficiently in a single monorepo, but deliver fully isolated build artifacts for each customer.

**Workflow Overview:**

#### Unified Development (in Monorepo)

- The `packages/` directory contains the Base Layer: all shared UI components, core logic, and API clients used by every customer.
- The `apps/` directory contains the Custom Layer: independent Remix applications for each customer, with their own custom pages and logic.
- Example: `apps/medytox` imports and uses `packages/shared-ui`.

#### Customer-specific Build (in CI/CD Pipeline)

- The CI/CD pipeline targets and builds only the relevant customer app.
- For example, to build for Medytox, run: `turbo build --filter=medytox`.
- The build output is a fully independent, executable application containing only the code needed for that customer.

#### Packaging & Delivery (Docker)

- The built output (e.g., `apps/medytox/.build`) is packaged as a **Docker image**. Each customer app folder contains its own Dockerfile to automate this.
- This Docker image is the final software delivered to the customer.

#### On-Premise Deployment

- The customer simply runs the delivered Docker image on their own server environment.

**Key Advantages in On-Premise Environments:**

- **Complete Isolation:** Each customer receives a fully independent application, with no risk of code or configuration leakage between customers—maximizing security and stability.
- **Efficient Maintenance:** Fixes or updates to the Base Layer (`packages/shared-ui`, etc.) only require rebuilding and delivering the affected customer apps.
- **Clear Code Management:** Shared and customer-specific code are physically separated, making management and onboarding of new customers straightforward.
- **Flexible Customization:** Any customization can be freely implemented inside `apps/{customer_name}` without affecting others.

**Conclusion:**  
For on-premise delivery, generating fully independent build artifacts per customer at build-time (rather than using runtime composition like MFE) is the standard and most robust approach. The package-based monorepo strategy is optimal for this model.

---

### Q-Hub Monorepo Layer Structure

This approach clearly separates base and custom code within a single Git repository using directory structure:

#### 1. Base Layer: `packages/` Directory

- **Purpose:** Core features and UI shared by all customers, managed as reusable packages.
- **Examples:**
  - `packages/shared-ui`: Common UI components (buttons, layouts, charts, etc.)
  - `packages/core-logic`: Core business logic (authentication, API calls, etc.)
- **Role:** Foundation and shared library for the entire system.

#### 2. Custom Layer: `apps/` Directory

- **Purpose:** Customer-specific code and configuration. Each customer has a dedicated app folder.
- **Examples:**
  - `apps/medytox`: App for Medytox customer.
  - `apps/customer-a`: App for Customer A.
- **Role:** Imports base packages and implements customer-specific pages, features, and branding.

#### Summary Table

| Layer        | Role                | Directory         | Keywords                    |
|--------------|---------------------|-------------------|-----------------------------|
| Base Layer   | Shared core logic   | `packages/*`      | Core Logic, Shared UI       |
| Custom Layer | Customer-specific   | `apps/{customer}` | Customer-Specific App       |

This structure enables efficient propagation of base layer updates to all custom layers, greatly improving **reusability** and **maintainability**. The CI/CD pipeline builds each customer app in `apps/` as a fully independent deliverable.

---

### Decision

As the number of customers increases, the **package-based monorepo** approach is vastly superior to the branch-based approach. Q-Hub will officially adopt the package-based monorepo strategy for managing customer customizations.

### Consequences

**Comparison Table:**

| Aspect | Branch-based | Package-based Monorepo |
| :--- | :--- | :--- |
| **Core Idea** | One branch per customer, code is copied and isolated | Shared/custom code separated into packages in one repo |
| **Base Layer Updates** | Manual merge/cherry-pick to all customer branches (merge hell) | Update shared package once, rebuild affected apps |
| **Code Visibility/Reusability** | Poor; hard to track customizations, code duplication likely | Excellent; all code visible, easy to promote shared logic, minimal duplication |
| **docker-compose Management** | Each branch has its own file; updating requires editing all branches | Each customer app has its own file in a central location; easy bulk updates |
| **CI/CD Pipeline** | Complex and inefficient; must monitor many branches | Simple and efficient; monitor only main, build only affected apps |
| **Scalability** | Poor; maintenance cost grows rapidly with customer count | Excellent; maintenance cost grows linearly, can handle 100+ customers |

**Scenario Example:**  
If a backend API changes and all frontends must update their API calls:
- *Branch-based:* Update main branch, then merge/cherry-pick into every customer branch, resolving conflicts each time, then build and deploy each branch.
- *Package-based Monorepo:* Update the shared API client package once, bump its version, and CI/CD automatically rebuilds and deploys all affected customer apps.

### Conclusion

Branch-based management may seem simple for a handful of customers, but quickly becomes a maintenance nightmare as the customer base grows.  
The package-based monorepo approach requires some initial setup and learning, but dramatically reduces maintenance costs and enables scalable, professional management of customer customizations.  
Especially in on-premise environments using `docker-compose`, the advantages of this approach are maximized. Q-Hub strongly recommends and will standardize on the package-based monorepo strategy.