## 🧠 Development Philosophy

At ego.cx, code isn't just code. It's the invisible structure that supports the digital identity of brands and professionals. Every line should be **clear, maintainable, and creative**.

**Our principles are:**
- **KISS** — Keep It Simple, Stupid. The simplest solution is almost always the best.
- **DRY** — Don't Repeat Yourself. Reuse is sacred.
- **YAGNI** — You Aren't Gonna Need It. Don't build for the future; build for now.
- **Disruption with purpose** — Innovating isn't doing weird things. It's doing what works in a way no one else is doing.

---

## 📋 Golden Rules of Development

### 1. Code is read more than it's written.
Write code as if the person maintaining it is a new colleague. Or your future self in 6 months.

✅ *"Clear and consistent names."*
❌ *"Cryptic abbreviations and convoluted logic."*

### 2. Each component has one responsibility.
One file, one function, one task. Separate to master.

✅ *"button.js → buttons only."*
❌ *"ui-components.js → buttons, modals, tooltips, and forms."*

### 3. Performance isn't a luxury; it's a requirement.
Code should be fast by default. Don't optimize at the end; optimize from the start.

✅ *"Lazy loading by default."*
❌ *"Load everything upfront and fix it later."*

### 4. Document as you write.
Code that needs explanation should be better code. But if it needs to be explained, do it.

✅ *"// This hook handles OAuth2 authentication"*
❌ *"// Does things"*

### 5. CSS isn't an accident.
Use semantic classes. Don't use `!important`. Use CSS variables. Make design part of the system.

✅ *"class="button-primary""*
❌ *"style="color: red; font-size: 16px;""*

---

## 🛠️ File and Project Structure

```
project/
├── src/
│   ├── components/           # Reusable components
│   │   ├── Button/
│   │   │   ├── Button.jsx
│   │   │   ├── Button.css
│   │   │   └── Button.test.js
│   │   └── Card/
│   │       ├── Card.jsx
│   │       ├── Card.css
│   │       └── Card.test.js
│   ├── pages/                # Specific pages
│   │   ├── Home/
│   │   ├── Product/
│   │   └── About/
│   ├── hooks/                # Custom hooks
│   │   ├── useAuth.js
│   │   └── useTheme.js
│   ├── utils/                # Utility functions
│   │   ├── formatDate.js
│   │   └── validateEmail.js
│   ├── styles/               # Global styles and variables
│   │   ├── variables.css
│   │   └── global.css
│   └── config/               # Configurations
│       └── constants.js
├── public/                   # Static files
│   ├── images/
│   └── fonts/
├── tests/                    # Integration tests
├── README.md
├── LICENSE
└── package.json
```

---

## 🎨 Code Style Guide

### JavaScript / TypeScript

✅ **Variable names in camelCase**
```javascript
const userName = 'Carlos';
const isAuthenticated = true;
```

✅ **Function names: verbs + nouns**
```javascript
function getUserData() { ... }
function validateEmail() { ... }
```

✅ **Components in PascalCase**
```javascript
function ButtonPrimary({ children, onClick }) { ... }
function CardFeature({ title, description }) { ... }
```

✅ **Constants in UPPER_SNAKE_CASE**
```javascript
const API_URL = 'https://api.ego.cx/v1';
const MAX_RETRIES = 3;
```

✅ **Use arrow functions for pure functions**
```javascript
const sum = (a, b) => a + b;
```

✅ **Use async/await for promises**
```javascript
const fetchData = async (url) => {
  const response = await fetch(url);
  return response.json();
};
```

### CSS / SCSS

✅ **CSS variables first**
```css
:root {
  --color-primary: #DC0000;
  --spacing-base: 4px;
  --font-family-base: 'Inter', sans-serif;
}
```

✅ **Semantic and utility classes**
```css
.button-primary {
  background: var(--color-primary);
  padding: 12px 24px;
  border-radius: 4px;
}
```

✅ **Use the base spacing system**
```css
.card {
  padding: calc(var(--spacing-base) * 4); /* 16px */
  margin-bottom: calc(var(--spacing-base) * 6); /* 24px */
}
```

---

## 🤖 AI and Copilots: How to Use Them Well

### Principles for Programming with AI

1. **Context is power.** Give the copilot full context: the file, dependencies, and purpose.
2. **Review before trusting.** AI writes code fast; you know if it's correct.
3. **Ask for explanations.** Not just code; ask *why* it chose that solution.
4. **Iterate.** The first attempt is rarely the best. Ask for alternatives.
5. **Maintain consistency.** AI can jump between styles. Guide it with examples.

### Sample Copilot Prompts

#### 🧩 Generate a Component
```
Create a Button component in React with TypeScript.
It must have:
- Props: variant (primary | secondary), size (sm | md | lg), onClick, children
- Use CSS Modules for styles
- Include comments for each prop
- Follow the ego.cx design system (colors #DC0000, #181716, #FCFCFC)
```

#### 🛠️ Optimize a Function
```
This function processes a list of users:
[insert code]

Optimize it to:
1. Reduce O(n²) complexity to O(n)
2. Use modern array methods (map, filter, reduce)
3. Maintain readability
4. Add comments about the optimization
```

#### 📄 Refactor CSS
```
Refactor this CSS to use CSS variables and a 4px spacing system:

[insert code]

It must maintain exactly the same visual appearance.
```

---

## 🧪 Testing and Quality

### Principles

1. **Write tests before or during, not after.**
2. **Each component has its own test.**
3. **Tests must be fast and deterministic.**
4. **Mock external dependencies, test internal logic.**

### Test Structure

```javascript
// Button.test.js
import { render, fireEvent } from '@testing-library/react';
import { ButtonPrimary } from './Button';

describe('ButtonPrimary', () => {
  it('renders with the correct text', () => {
    const { getByText } = render(<ButtonPrimary>Click me</ButtonPrimary>);
    expect(getByText('Click me')).toBeInTheDocument();
  });

  it('executes onClick when clicked', () => {
    const handleClick = jest.fn();
    const { getByText } = render(
      <ButtonPrimary onClick={handleClick}>Click me</ButtonPrimary>
    );
    fireEvent.click(getByText('Click me'));
    expect(handleClick).toHaveBeenCalled();
  });
});
```

---

## 🚀 Deployment and Monitoring

### Deployment Checklist

- [ ] All tests pass
- [ ] Linter has no errors
- [ ] Bundle optimized (code splitting, tree shaking)
- [ ] Assets compressed (WebP, AVIF, minified)
- [ ] Environment variables configured
- [ ] Error logging configured
- [ ] Performance metrics (Core Web Vitals)

### Monitoring

- **Errors:** Sentry / LogRocket
- **Performance:** Lighthouse / Web Vitals
- **Analytics:** Google Analytics / Plausible / Umami

---

## 📚 Resources and References

- [React Documentation](https://react.dev)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
- [CSS Variables Guide](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
- [KISS Principle](https://en.wikipedia.org/wiki/KISS_principle)
- [DRY Principle](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)


---

*— Fernando José Caicedo Albarello*  
*Founder, EgoCX*