BLISS FRAMEWORK - CLAUDE CODE NAMING CONVENTIONS
Version: 1.0.0
Last Modified: 2025-01-19T00:00:00Z
Category: Core Guidelines
Priority: Critical

Standardized naming patterns across all projects and technologies.

=== GENERAL RULES ===

Universal Principles:
1. Descriptive over Short - getUserById() not getUser()
2. No Abbreviations - userManager not usrMgr
3. Consistent Language - All names in English
4. No Magic Numbers - Use named constants

Casing Standards:
- camelCase: Variables, functions, methods
- PascalCase: Classes, interfaces, components, types
- kebab-case: Files, URLs, CSS classes
- SCREAMING_SNAKE_CASE: Constants, environment variables
- snake_case: Database tables, columns

=== FILES AND FOLDERS ===

File Naming:
✓ Good:
- user-provider.ts
- order-manager.ts
- payment-service.ts
- user-profile.component.svelte

✗ Bad:
- UserProvider.ts
- orderMgr.ts
- payment_service.ts

Standard Folder Structure:
src/
├── providers/
├── managers/
├── io/
├── models/
├── mappers/
├── helpers/
├── constants/
└── types/

=== FUNCTIONS AND METHODS ===

CRUD Operations:
- getUserById(id: string)
- createUser(userData: CreateUserRequest)
- updateUser(id: string, changes: UpdateUserRequest)
- deleteUser(id: string)

Boolean Functions:
- isValid(data: unknown): boolean
- hasPermission(user: User, action: string): boolean
- canAccess(resource: Resource): boolean

Async Functions:
- async fetchUsers(): Promise<User[]>
- async saveUser(user: User): Promise<void>

Validation:
- validateEmail(email: string): ValidationResult
- validatePassword(password: string): ValidationResult

Transformation:
- mapUserToDto(user: User): UserDto
- parseUserInput(input: string): ParsedUser

Function Categories:
- get/fetch: Retrieve data (get = sync, fetch = async)
- create/add: Create new entities
- update/modify: Change existing entities
- delete/remove: Remove entities
- validate: Check data validity
- parse: Convert data formats
- map: Transform data structures
- calculate: Perform computations
- generate: Create derived data

=== VARIABLES ===

Descriptive Names:
✓ Good:
- const userAccountBalance = 150.50;
- const isUserLoggedIn = checkAuth();
- const maxRetryAttempts = 3;

✗ Bad:
- const balance = 150.50;
- const loggedIn = checkAuth();
- const max = 3;

Collection Names:
- const users = []; // plural
- const userList = []; // explicit list
- const activeUsers = []; // descriptive

Maps/Objects:
- const userById = new Map();
- const configByEnvironment = {};

Sets:
- const uniqueUserIds = new Set();
- const visitedPages = new Set();

=== CLASSES AND INTERFACES ===

Classes:
- class UserProvider {}
- class OrderManager {}
- class PaymentService {}
- class User {}
- class Order {}
- class DateHelper {}

Interfaces:
- interface User {}
- interface CreateUserRequest {}
- interface UserResponse {}
- interface UserProvider {}
- interface PaymentGateway {}
- interface DatabaseConfig {}

=== DATABASE NAMING ===

Tables (singular, snake_case):
- users
- user_accounts
- order_items
- payment_transactions

Columns (snake_case):
- user_id
- email_address
- created_at
- updated_at
- is_active
- account_balance

Foreign keys (with table prefix):
- user_id (references users.id)
- order_id (references orders.id)

Indexes (idx_table_column):
- idx_users_email
- idx_orders_user_id_created_at
- idx_payments_status_date

=== CONSTANTS AND ENUMS ===

Constants (SCREAMING_SNAKE_CASE):
- const MAX_LOGIN_ATTEMPTS = 3;
- const DEFAULT_PAGE_SIZE = 20;
- const API_BASE_URL = 'https://api.example.com';
- const ERROR_USER_NOT_FOUND = 'User not found';

Enums (PascalCase with descriptive values):
enum UserStatus {
    Active = 'active',
    Inactive = 'inactive',
    Suspended = 'suspended'
}

enum PaymentAction {
    Charge = 'charge',
    Refund = 'refund',
    Authorize = 'authorize'
}

=== COMPONENT NAMING ===

Component Files (PascalCase.svelte):
- UserProfile.svelte
- OrderSummary.svelte
- PaymentForm.svelte
- UserDashboard.svelte

Component Properties (camelCase):
interface UserProfileProps {
    userId: string;
    showActions: boolean;
    onUserUpdate: (user: User) => void;
}

=== API NAMING ===

RESTful Endpoints:
- GET    /api/users           # Get all users
- GET    /api/users/{id}      # Get specific user
- POST   /api/users           # Create user
- PUT    /api/users/{id}      # Update user
- DELETE /api/users/{id}      # Delete user

Action Endpoints:
- POST   /api/users/{id}/activate
- POST   /api/orders/{id}/cancel
- POST   /api/payments/{id}/refund

Request/Response Types:
- interface CreateUserRequest {}
- interface UpdateOrderRequest {}
- interface UserResponse {}
- interface OrderListResponse {}

=== ENVIRONMENT VARIABLES ===

Naming Pattern (COMPONENT_PURPOSE_DETAIL):
- DATABASE_CONNECTION_STRING
- API_BASE_URL
- REDIS_CACHE_HOST
- SMTP_SERVER_HOST
- JWT_SECRET_KEY

Environment Specific:
- DEV_DATABASE_URL
- PROD_DATABASE_URL
- TEST_API_KEY

=== TEST FILES ===

Test File Names ([component].test.[ext]):
- user-provider.test.ts
- order-manager.test.ts
- payment-service.test.ts
- user-api.integration.test.ts

Test Function Names:
describe('UserProvider', () => {
    describe('getUserById', () => {
        it('should return user when id exists', () => {});
        it('should return null when id does not exist', () => {});
        it('should throw error when id is invalid', () => {});
    });
});

=== ANTI-PATTERNS TO AVOID ===

Bad Examples:
✗ const data = fetchStuff(); // Too generic
✗ const result = doThing(); // Too generic
✗ const getUsersAsync(); // Not actually async
✗ const user = getUsers(); // Returns array
✗ const usrMgr = new UserManager(); // Abbreviations
✗ const btnClk = handleClick; // Abbreviations
✗ const user_id = 1; // Wrong casing context
✗ const UserID = 2; // Inconsistent casing

Good Alternatives:
✓ const userAccounts = fetchUserAccounts();
✓ const validationResult = validateUserInput();
✓ const getUsers(); // sync function
✓ const fetchUsersAsync(); // async function
✓ const userManager = new UserManager();
✓ const handleButtonClick = handleClick;
✓ const userId = 1;
✓ const userAccountId = 2;