Chat2DB

Controllers must depend on business capabilities exclusively through IxxxService interfaces found in the ai.chat2db.community.domain.api.service package.

Allowed Dependencies

• Domain-api service interfaces.
• Web converters/convertors.
• HTTP binding types (MultipartFile, HttpServletResponse, Request/Response DTOs).
• Standard result wrapper types.

Prohibited Dependencies

• *Impl classes, mappers, repositories, DAOs, or storage implementations.
• Any interface or implementation under ai.chat2db.community.web.api.service (this layer is prohibited for controllers).
• GatewayUtil, WorkspaceStorageWebFacade, task managers, or web adapters.
• ApplicationContext#getBean or reflection-based access to implementations.

Chat2DB Community uses AES-256-GCM to encrypt database passwords and AI model API keys. Each instance requires a unique key.

Key Generation: Run the following script in the repository directory to generate a key. This requires openssl.

./script/security/init-community-encryption-key.sh

By default, the key is saved to ~/.config/chat2db-community/encryption.key.

Critical Security Note:

• Backup this file. If lost, you cannot decrypt saved credentials.
• Keep it secure. The file should only be readable by the user running the Chat2DB process.
• Desktop vs Web/Headless: In Desktop mode, Chat2DB will automatically create a key if one is missing. In Web or Headless modes, the application will fail to start if a valid key is not explicitly configured.

Chat2DB Community

Includes all local database client features, such as support for custom AI models.

Chat2DB Pro and Enterprise

Built on the same core as the Community version, but adds:

• Hosted AI services
• User accounts
• Cloud storage and multi-device synchronization
• Team collaboration and governance features

When organizing Maven modules, follow a specific hierarchy for classification packages. Classification packages must be the first segment after the module root package.

Allowed Classification Packages:

• enums
• constant (Note: use singular constant, not constants)
• model
• config

Structure Rules:

1. A classification package can contain business subpackages (e.g., enums/completion).
2. Do not place a classification package below a business package (e.g., completion/enums is forbidden).
3. Business-related source packages should use db instead of rdb (e.g., ai.chat2db.community.domain.core.constant.db.doc).

Example Structure:

• ai.chat2db.plugin.mysql.enums.completion
• ai.chat2db.plugin.mysql.model.completion.context
• ai.chat2db.plugin.mysql.config.completion

The following use cases do not require a formal converter, but must remain narrowly scoped:

• Static Factories: A static factory on an object that enforces its own invariants without copying fields from another layer.
• Value Parsers: Enums or value-objects returning their own type (e.g., fromCode, fromValue).
• Raw Value Processing: SQL/JDBC processors returning String, byte[], primitives, or raw driver objects.
• Exception Adaptation: Adapting an exception into an HTTP error result.
• Test Data: Test code constructing test fixtures or mocks.
• Startup/Config: Startup assembly or configuration code creating beans or configuration property objects (without mapping business objects).

When contributing to the Community frontend, adhere to these coding standards:

• TypeScript: Prefix all TypeScript interfaces and type aliases with I.
• Theming: Do not use hard-coded theme colors. Use values from window._AppThemePack in JavaScript or CSS variables (e.g., var(--control-item-bg-active)) in styles.
• Internationalization (i18n):
  • Use keys from src/i18n/ via i18n or i18nElement.
  • Use {1}, {2}, etc., for placeholders.
  • Spanish and Korean catalogs must maintain exact parity (module, key, placeholder, and HTML-tag) with the en-US catalog. Update source hashes whenever English wording changes.

To maintain stable and replaceable contracts, all Java interfaces must follow specific naming conventions:

• Prefix: Every interface must start with an I (e.g., IDataSourceService).
• Business Services: Use the pattern IXxxService.
• Storage/Repositories: Use IXxxStorage or IXxxRepository.
• Plugins/Extensions: Use capability suffixes like IXxxManager, IXxxDialect, IXxxPlugin, or IXxxProcessor.
• Callbacks/Listeners: Use I prefix (e.g., IProgressListener).
• Implementations: Name implementation classes XxxServiceImpl and explicitly declare implements IXxxService.

Business service interfaces must also include a top-level domain prefix (see Domain Prefix Reference).

public interface IDataSourceService {
}

public class DataSourceServiceImpl implements IDataSourceService {
}

Chat2DB Community is a single-user, local-first application. It does not provide user accounts or permission boundaries between multiple users.

Security Guidelines:

• Network Exposure: Keep the HTTP service bound to 127.0.0.1 or ::1. Do not expose it to untrusted networks.
• JDBC Drivers: Custom JDBC drivers are executable Java code. Only install drivers from trusted sources.
• Data Trust: Treat all imported configuration files, compressed files, SQL files, database contents, and AI responses as untrusted data.

When contributing to the frontend source, adhere to these rules to ensure CI compliance:

• Zero Tolerance: Maintained source must pass with zero errors and zero warnings. Do not disable or downgrade rules to bypass CI; instead, fix the source or update the rule only if the project runtime or syntax contract has changed.
• Unused Parameters: Any intentionally unused callback parameters must be prefixed with an underscore (e.g., _param).
• CSS Naming:
  • CSS module classes can use camelCase or kebab-case.
  • Global third-party class names may use PascalCase.