chore: add doc for adding new abstractions to codebase (#10444)

* chore: add doc for adding new abstractions to codebase

* chore: reorder

---------

Co-authored-by: Pandey <vibhupandey28@gmail.com>

docs/contributing/go/abstractions.md

@@ -0,0 +1,127 @@
+# Abstractions
+
+This document provides rules for deciding when a new type, interface, or intermediate representation is warranted in Go code. The goal is to keep the codebase navigable by ensuring every abstraction earns its place.
+
+## The cost of a new abstraction
+
+Every exported type, interface, or wrapper is a permanent commitment. It must be named, documented, tested, and understood by every future contributor. It creates a new concept in the codebase vocabulary. Before introducing one, verify that the cost is justified by a concrete benefit that cannot be achieved with existing mechanisms.
+
+## Before you introduce anything new
+
+Answer these four questions. If writing a PR, include the answers in the description.
+
+1. **What already exists?** Name the specific type, function, interface, or library that covers this ground today.
+2. **What does the new abstraction add?** Name the concrete operation, guarantee, or capability. "Cleaner" or "more reusable" are not sufficient; name what the caller can do that it could not do before.
+3. **What does the new abstraction drop?** If it wraps or mirrors an existing structure, list what it cannot represent. Every gap must be either justified or handled with an explicit error.
+4. **Who consumes it?** List the call sites. If there is only one producer and one consumer in the same call chain, you likely need a function, not a type.
+
+## Rules
+
+### 1. Prefer functions over types
+
+If a piece of logic has one input and one output, write a function. Do not create a struct to hold intermediate state that is built in one place and read in one place. A function is easier to test, easier to inline, and does not expand the vocabulary of the codebase.
+
+```go
+// Prefer this:
+func ConvertConfig(src ExternalConfig) (InternalConfig, error)
+
+// Over this:
+type ConfigAdapter struct { ... }
+func NewConfigAdapter(src ExternalConfig) *ConfigAdapter
+func (a *ConfigAdapter) ToInternal() (InternalConfig, error)
+```
+
+The two-step version is only justified when `ConfigAdapter` has multiple distinct consumers that use it in different ways.
+
+### 2. Do not duplicate structures you do not own
+
+When a library or external package produces a structured output, operate on that output directly. Do not create a parallel type that mirrors a subset of its fields.
+
+A partial copy will:
+- **Silently lose data** when the source has fields or variants the copy does not account for.
+- **Drift** when the source evolves and the copy is not updated in lockstep.
+- **Add a conversion step** that doubles the code surface and the opportunity for bugs.
+
+If you need to shield consumers from a dependency, define a narrow interface over the dependency's type rather than copying its shape into a new struct.
+
+### 3. Never silently discard input
+
+If your code receives structured input and cannot handle part of it, return an error. Do not silently return nil, skip the element, or produce a partial result. Silent data loss is the hardest class of bug to detect because the code appears to work, it just produces wrong results.
+
+```go
+// Wrong: silently ignores the unrecognized case.
+default:
+    return nil
+
+// Right: makes the gap visible.
+default:
+    return nil, fmt.Errorf("unsupported %T value: %v", v, v)
+```
+
+This applies broadly: type switches, format conversions, data migrations, enum mappings, configuration parsing. Anywhere a `default` or `else` branch can swallow input, it should surface an error instead.
+
+### 4. Do not expose methods that lose information
+
+A method on a structured type should not strip meaning from the structure it belongs to. If a caller needs to iterate over elements for a specific purpose (validation, aggregation, logging), write that logic as a standalone function that operates on the structure with full context, rather than adding a method that returns a reduced view.
+
+```go
+// Problematic: callers cannot distinguish how items were related.
+func (o *Order) AllLineItems() []LineItem { ... }
+
+// Better: the validation logic operates on the full structure.
+func ValidateOrder(o *Order) error { ... }
+```
+
+Public methods shape how a type is used. Once a lossy accessor exists, callers will depend on it, and the lost information becomes unrecoverable at those call sites.
+
+### 5. Interfaces should be discovered, not predicted
+
+Do not define an interface before you have at least two concrete implementations that need it. An interface with one implementation is not abstraction; it is indirection that makes it harder to navigate from call site to implementation.
+
+The exception is interfaces required for testing (e.g., for mocking an external dependency). In that case, define the interface in the **consuming** package, not the providing package, following the Go convention of [accepting interfaces and returning structs](https://go.dev/wiki/CodeReviewComments#interfaces).
+
+### 6. Wrappers must add semantics, not just rename
+
+A wrapper type is justified when it adds meaning, validation, or invariants that the underlying type does not carry. It is not justified when it merely renames fields or reorganizes the same data into a different shape.
+
+```go
+// Justified: adds validation that the underlying string does not carry.
+type OrgID struct{ value string }
+func NewOrgID(s string) (OrgID, error) { /* validates format */ }
+
+// Not justified: renames fields with no new invariant or behavior.
+type UserInfo struct {
+    Name  string // same as source.Name
+    Email string // same as source.Email
+}
+```
+
+Ask: what does the wrapper guarantee that the underlying type does not? If the answer is nothing, use the underlying type directly.
+
+## When a new type IS warranted
+
+A new type earns its place when it meets **at least one** of these criteria:
+
+- **Serialization boundary**: It must be persisted, sent over the wire, or written to config. The source type is unsuitable (unexported fields, function pointers, cycles).
+- **Invariant enforcement**: The constructor or methods enforce constraints that raw data does not carry (e.g., non-empty, validated format, bounded range).
+- **Multiple distinct consumers**: Three or more call sites use the type in meaningfully different ways. The type is the shared vocabulary between them.
+- **Dependency firewall**: The type lives in a lightweight package so that consumers avoid importing a heavy dependency.
+
+## What should I remember?
+
+- A function is almost always simpler than a type. Start with a function; promote to a type only when you have evidence of need.
+- Never silently drop data. If you cannot handle it, error.
+- If your new type mirrors an existing one, you need a strong reason beyond "nicer to work with".
+- If your type has one producer and one consumer, it is indirection, not abstraction.
+- Interfaces come from need (multiple implementations), not from prediction.
+- When in doubt, do not add it. It is easier to add an abstraction later when the need is clear than to remove one after it has spread through the codebase.
+
+## Further reading
+
+These works and our own lessions shaped the above guidelines
+
+- [The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction) - Sandi Metz. The wrong abstraction is worse than duplication. If you find yourself passing parameters and adding conditional paths through shared code, inline it back into every caller and let the duplication show you what the right abstraction is.
+- [Write code that is easy to delete, not easy to extend](https://programmingisterrible.com/post/139222674273/write-code-that-is-easy-to-delete-not-easy-to) - tef. Every abstraction is a bet on the future. Optimize for how cheaply you can remove code when the bet is wrong, not for how easily you can extend it when the bet is right.
+- [Goodbye, Clean Code](https://overreacted.io/goodbye-clean-code/) - Dan Abramov. A refactoring that removes duplication can look cleaner while making the code harder to change. Clean-looking and easy-to-change are not the same thing.
+- [A Philosophy of Software Design](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201) - John Ousterhout. Good abstractions are deep: simple interface, complex implementation. A "false abstraction" omits important details while appearing simple, and is worse than no abstraction at all. ([Summary by Pragmatic Engineer](https://blog.pragmaticengineer.com/a-philosophy-of-software-design-review/))
+- [Simplicity is Complicated](https://go.dev/talks/2015/simplicity-is-complicated.slide) - Rob Pike. Go-specific. Fewer orthogonal concepts that compose predictably beat many overlapping ones. Features were left out of Go deliberately; the same discipline applies to your own code.

docs/contributing/go/packages.md

@@ -0,0 +1,126 @@
+# Packages
+
+All shared Go code in SigNoz lives under `pkg/`. Each package represents a distinct domain concept and exposes a clear public interface. This guide covers the conventions for creating, naming, and organising packages so the codebase stays consistent as it grows.
+
+## How should I name a package?
+
+Use short, lowercase, single-word names. No underscores or camelCase (`querier`, `cache`, `authz`, not `query_builder` or `dataStore`).
+
+Names must be **domain-specific**. A package name should tell you what problem domain it deals with, not what data structure it wraps. Prefer `alertmanager` over `manager`, `licensing` over `checker`.
+
+Avoid generic names like `util`, `helpers`, `common`, `misc`, or `base`. If you can't name it, the code probably belongs in an existing package.
+
+## When should I create a new package?
+
+Create a new package when:
+
+- The functionality represents a **distinct domain concept** (e.g., `authz`, `licensing`, `cache`).
+- Two or more other packages would import it; it serves as shared infrastructure.
+- The code has a clear public interface that can stand on its own.
+
+Do **not** create a new package when:
+
+- There is already a package that covers the same domain. Extend the existing package instead.
+- The code is only used in one place. Keep it local to the caller.
+- You are splitting purely for file size. Use multiple files within the same package instead.
+
+## How should I lay out a package?
+
+A typical package looks like:
+
+```
+pkg/cache/
+├── cache.go            # Public interface + exported types
+├── config.go           # Configuration types if needed
+├── memorycache/        # Implementation sub-package
+├── rediscache/         # Another implementation
+└── cachetest/          # Test helpers for consumers
+```
+
+Follow these rules:
+
+1. **Interface-first file**: The file matching the package name (e.g., `cache.go` in `pkg/cache/`) should define the public interface and core exported types. Keep implementation details out of this file.
+
+2. **One responsibility per file**: Name files after what they contain (`config.go`, `handler.go`, `service.go`), not after the package name. If a package merges two concerns, prefix files to group them (e.g., `memory_store.go`, `redis_store.go` in a storage package).
+
+3. **Sub-packages for implementations**: When a package defines an interface with multiple implementations, put each implementation in its own sub-package (`memorycache/`, `rediscache/`). This keeps the parent package import-free of implementation dependencies.
+
+4. **Test helpers in `{pkg}test/`**: If consumers need test mocks or builders, put them in a `{pkg}test/` sub-package (e.g., `cachetest/`, `sqlstoretest/`). This avoids polluting the main package with test-only code.
+
+5. **Test files stay alongside source**: Unit tests go in `_test.go` files next to the code they test, in the same package.
+
+## How should I name symbols?
+
+### Exported symbols
+
+- **Interfaces**: For single-method interfaces, follow the standard `-er` suffix convention (`Reader`, `Writer`, `Closer`). For multi-method interfaces, use clear nouns (`Cache`, `Store`, `Provider`).
+- **Constructors**: `New<Type>(...)` (e.g., `NewMemoryCache()`).
+- **Avoid stutter**: Since callers qualify with the package name, don't repeat it. Write `cache.Cache`, not `cache.CacheInterface`. Write `authz.FromRole`, not `authz.AuthzFromRole`.
+
+### Unexported symbols
+
+- Struct receivers: one or two characters (`c`, `f`, `br`).
+- Helper functions: descriptive lowercase names (`parseToken`, `buildQuery`).
+
+### Constants
+
+- Use `PascalCase` for exported constants.
+- When merging files from different origins into one package, watch out for **name collisions** across files. Prefix to disambiguate when two types share a natural name.
+
+## How should I organise imports?
+
+Group imports in three blocks separated by blank lines:
+
+```go
+import (
+    // 1. Standard library
+    "fmt"
+    "net/http"
+
+    // 2. External dependencies
+    "github.com/gorilla/mux"
+
+    // 3. Internal
+    "github.com/SigNoz/signoz/pkg/errors"
+    "github.com/SigNoz/signoz/pkg/types"
+)
+```
+
+Never introduce circular imports. If package A needs package B and B needs A, extract the shared types into a third package (often under `pkg/types/`).
+
+## Where do shared types go?
+
+Most types belong in `pkg/types/` under a domain-specific sub-package (e.g., `pkg/types/ruletypes`, `pkg/types/authtypes`).
+
+Do not put domain logic in `pkg/types/`. Only data structures, constants, and simple methods.
+
+## How do I merge or move packages?
+
+When two packages are tightly coupled (one imports the other's constants, they cover the same domain), merge them:
+
+1. Pick a domain-specific name for the combined package.
+2. Prefix files to preserve origin (e.g., `memory_store.go`, `redis_store.go`).
+3. Resolve symbol conflicts explicitly; rename with a prefix rather than silently shadowing.
+4. Update all consumers in a single change.
+5. Delete the old packages. Do not leave behind re-export shims.
+6. Verify with `go build ./...`, `go test ./<new-pkg>/...`, and `go vet ./...`.
+
+## When should I add documentation?
+
+Add a `doc.go` with a package-level comment for any package that is non-trivial or has multiple consumers. Keep it to 1–3 sentences:
+
+```go
+// Package cache provides a caching interface with pluggable backends
+// for in-memory and Redis-based storage.
+package cache
+```
+
+## What should I remember?
+
+- Package names are domain-specific and lowercase. Never generic names like `util` or `common`.
+- The file matching the package name (e.g., `cache.go`) defines the public interface. Implementation details go elsewhere.
+- Never introduce circular imports. Extract shared types into `pkg/types/` when needed.
+- Watch for symbol name collisions when merging packages, prefix to disambiguate.
+- Put test helpers in a `{pkg}test/` sub-package, not in the main package.
+- Before submitting, verify with `go build ./...`, `go test ./<your-pkg>/...`, and `go vet ./...`.
+- Update all consumers when you rename or move symbols.

docs/contributing/go/readme.md

@@ -8,4 +8,14 @@ We adhere to three primary style guides as our foundation:
 - [Code Review Comments](https://go.dev/wiki/CodeReviewComments) - For understanding common comments in code reviews
 - [Google Style Guide](https://google.github.io/styleguide/go/) - Additional practices from Google
 
-We **recommend** (almost enforce) reviewing these guides before contributing to the codebase. They provide valuable insights into writing idiomatic Go code and will help you understand our approach to backend development. In addition, we have a few additional rules that make certain areas stricter than the above which can be found in area-specific files in this package.
+We **recommend** (almost enforce) reviewing these guides before contributing to the codebase. They provide valuable insights into writing idiomatic Go code and will help you understand our approach to backend development. In addition, we have a few additional rules that make certain areas stricter than the above which can be found in area-specific files in this package:
+
+- [Abstractions](abstractions.md) - When to introduce new types and intermediate representations
+- [Errors](errors.md) - Structured error handling
+- [Endpoint](endpoint.md) - HTTP endpoint patterns
+- [Flagger](flagger.md) - Feature flag patterns
+- [Handler](handler.md) - HTTP handler patterns
+- [Integration](integration.md) - Integration testing
+- [Provider](provider.md) - Dependency injection and provider patterns
+- [Packages](packages.md) — Naming, layout, and conventions for `pkg/` packages
+- [SQL](sql.md) - Database and SQL patterns

frontend/src/container/Download/Download.tsx

@@ -1,6 +1,6 @@
+import { useState } from 'react';
 import { CloudDownloadOutlined } from '@ant-design/icons';
 import { Button, Dropdown, MenuProps } from 'antd';
-import { Excel } from 'antd-table-saveas-excel';
 import { unparse } from 'papaparse';
 
 import { DownloadProps } from './Download.types';
@@ -8,25 +8,36 @@ import { DownloadProps } from './Download.types';
 import './Download.styles.scss';
 
 function Download({ data, isLoading, fileName }: DownloadProps): JSX.Element {
-	const downloadExcelFile = (): void => {
-		const headers = Object.keys(Object.assign({}, ...data)).map((item) => {
-			const updatedTitle = item
-				.split('_')
-				.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-				.join(' ');
-			return {
-				title: updatedTitle,
-				dataIndex: item,
-			};
-		});
-		const excel = new Excel();
-		excel
-			.addSheet(fileName)
-			.addColumns(headers)
-			.addDataSource(data, {
-				str2Percent: true,
-			})
-			.saveAs(`${fileName}.xlsx`);
+	const [isDownloading, setIsDownloading] = useState(false);
+
+	const downloadExcelFile = async (): Promise<void> => {
+		setIsDownloading(true);
+
+		try {
+			const headers = Object.keys(Object.assign({}, ...data)).map((item) => {
+				const updatedTitle = item
+					.split('_')
+					.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+					.join(' ');
+				return {
+					title: updatedTitle,
+					dataIndex: item,
+				};
+			});
+
+			const excelLib = await import('antd-table-saveas-excel');
+
+			const excel = new excelLib.Excel();
+			excel
+				.addSheet(fileName)
+				.addColumns(headers)
+				.addDataSource(data, {
+					str2Percent: true,
+				})
+				.saveAs(`${fileName}.xlsx`);
+		} finally {
+			setIsDownloading(false);
+		}
 	};
 
 	const downloadCsvFile = (): void => {
@@ -59,7 +70,7 @@ function Download({ data, isLoading, fileName }: DownloadProps): JSX.Element {
 		<Dropdown menu={menu} trigger={['click']}>
 			<Button
 				className="download-button"
-				loading={isLoading}
+				loading={isLoading || isDownloading}
 				size="small"
 				type="link"
 			>

frontend/src/container/DownloadV2/DownloadV2.tsx

@@ -1,5 +1,5 @@
+import { useState } from 'react';
 import { Button, Popover, Typography } from 'antd';
-import { Excel } from 'antd-table-saveas-excel';
 import { FileDigit, FileDown, Sheet } from 'lucide-react';
 import { unparse } from 'papaparse';
 
@@ -8,25 +8,34 @@ import { DownloadProps } from './DownloadV2.types';
 import './DownloadV2.styles.scss';
 
 function Download({ data, isLoading, fileName }: DownloadProps): JSX.Element {
-	const downloadExcelFile = (): void => {
-		const headers = Object.keys(Object.assign({}, ...data)).map((item) => {
-			const updatedTitle = item
-				.split('_')
-				.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-				.join(' ');
-			return {
-				title: updatedTitle,
-				dataIndex: item,
-			};
-		});
-		const excel = new Excel();
-		excel
-			.addSheet(fileName)
-			.addColumns(headers)
-			.addDataSource(data, {
-				str2Percent: true,
-			})
-			.saveAs(`${fileName}.xlsx`);
+	const [isDownloading, setIsDownloading] = useState(false);
+
+	const downloadExcelFile = async (): Promise<void> => {
+		setIsDownloading(true);
+
+		try {
+			const headers = Object.keys(Object.assign({}, ...data)).map((item) => {
+				const updatedTitle = item
+					.split('_')
+					.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+					.join(' ');
+				return {
+					title: updatedTitle,
+					dataIndex: item,
+				};
+			});
+			const excelLib = await import('antd-table-saveas-excel');
+			const excel = new excelLib.Excel();
+			excel
+				.addSheet(fileName)
+				.addColumns(headers)
+				.addDataSource(data, {
+					str2Percent: true,
+				})
+				.saveAs(`${fileName}.xlsx`);
+		} finally {
+			setIsDownloading(false);
+		}
 	};
 
 	const downloadCsvFile = (): void => {
@@ -54,6 +63,7 @@ function Download({ data, isLoading, fileName }: DownloadProps): JSX.Element {
 						type="text"
 						onClick={downloadExcelFile}
 						className="action-btns"
+						loading={isDownloading}
 					>
 						Excel (.xlsx)
 					</Button>