# Monch Agency - Full Technical Documentation
This document compiles the full technical and operational documentation of Monch Agency. It serves as a unified reference for search engines, AI agents, and developers.
---
## 1. Business Core
### 1.1 The Value Proposition
Monch Agency is not just a development studio; it is a **Lead Technical Partner** for high-stakes digital products. We bridge the gap between creative vision and engineering excellence.
#### Core Mission
To provide "Production-Grade" engineering solutions that are as visually stunning as they are technically robust, specifically focusing on the WordPress ecosystem and high-performance React applications.
### 1.2 The "Technical Partner" Philosophy
Unlike traditional agencies that focus on one-off deliveries, we operate as an extension of the client's team.
- **Precision over Volume**: We don't do everything. We specialize in complex, high-performance builds.
- **Architectural Integrity**: Every line of code must be scalable, maintainable, and secure.
- **The "Technical Sketchbook" Soul**: Our brand identity reflects the precision of a blueprint and the creativity of a master craftsman.
### 1.3 Service Pillars
1. **UX/UI Engineering**: Strategic design optimized for conversion and technical feasibility.
2. **High-Performance Development**: Custom builds with clean architectures (Vite, React, Modular CSS).
3. **Elite Maintenance**: 24/7 technical reliability and continuous optimization.
4. **WordPress Engineering**: Specialization in Bricks Builder and custom high-end WP ecosystems.
### 1.4 Market Positioning
We position ourselves at the intersection of **Industrial Reliability** and **Custom Craftsmanship**. We target clients who have outgrown standard solutions and need a partner capable of handling technical complexity with an artisan's touch.
---
## 2. System Design
### 2.1 Architectural Overview
The application is built using a **Modular Frontend Architecture** focused on performance, scalability, and ease of maintenance.
- **Engine**: Vite + React.
- **Paradigm**: Spec-Driven Development (SDD).
- **Styling**: Vanilla CSS with a Custom Modular System (No Utility Frameworks).
### 2.2 Directory Structure & Responsibilities
```
/src
/components
/ui: Atomic, reusable components (Buttons, Stickers, Inputs).
/layout: Global structural components (Navbar, Footer).
/sections: Isolated landing page sections (Hero, Services, Portfolio).
/styles
/tokens: Core design tokens (variables.css).
/base: Reset, global typography, and paper textures.
/components: Scoped styles for every component.
/pages: Route-level page assemblies.
/assets: Optimized images and illustrations.
```
### 2.3 Component Lifecycle
Every section component must follow this lifecycle:
1. **Spec Definition**: Documented in `doc/design/`.
2. **Implementation**: Isolated JSX + Scoped CSS.
3. **Animation**: Framer Motion for high-end micro-interactions.
4. **Verification**: Visual audit against the "Technical Sketchbook" specs.
### 2.4 State Management
- **Local State**: Preferred for UI interactions (Modals, Toggles, Sliders).
- **Context API**: Reserved for global concerns like Theme or Auth (if applicable).
- **No Heavy Redux**: Keep the bundle lean and the logic close to the consumer.
### 2.5 Backend Integration
- **Supabase**: Primary data engine for dynamic content, storage (Media), and potential auth.
- **Edge Functions**: Used for complex backend logic (e.g., Email dispatch via Resend).
---
## 3. Security Standards & Best Practices
As a Lead Technical Partner, security is not an afterthought. We implement industry standards to protect both the agency's assets and our clients' trust.
### 3.1 Frontend Security
- **Input Sanitization**: All user inputs (forms, search fields) must be sanitized before being used in React state or sent to the backend to prevent XSS (Cross-Site Scripting).
- **Environment Variables**: NEVER hardcode API keys or sensitive URIs. Use `.env` files and `import.meta.env`.
- **Security Headers**: Ensure the production build includes basic security headers (via Meta tags or hosting config):
- `Content-Security-Policy` (CSP)
- `X-Frame-Options: DENY`
- `X-Content-Type-Options: nosniff`
### 3.2 Supabase Security
- **RLS (Row Level Security)**: Every table must have RLS enabled. Policies should follow the "Principle of Least Privilege".
- **Secure Functions**: Database functions should use `SECURITY INVOKER` by default. Use `SECURITY DEFINER` only when absolutely necessary and restrict search paths.
- **Auth Tokens**: Use Supabase's built-in JWT handling for authenticated routes.
### 3.3 Communication Security
- **Email Dispatch**: Use trusted services like Resend via authenticated Edge Functions.
- **WhatsApp Integration**: Ensure links use official APIs and do not expose internal phone logic.
### 3.4 Maintenance & Audits
- **Package Audits**: Run `npm audit` regularly to patch dependency vulnerabilities.
- **Access Control**: Rotate API keys and database credentials every 90 days or after any staff change.
---
## 4. Coding Standards
### 4.1 File Naming
- **Components**: PascalCase (e.g., `HeroSection.jsx`).
- **Styles**: kebab-case matching the component (e.g., `hero-section.css`).
- **Hooks/Utils**: camelCase (e.g., `useScroll.js`).
### 4.2 Component Template
Every Section component should follow this template:
```jsx
import React from 'react';
import '../../styles/components/component-name.css';
/**
* [Component Name]
* Purpose: [Describe what this section does]
* @returns {JSX.Element}
*/
export const ComponentName = () => {
return (
{/* Content */}
);
};
```
### 4.3 Documentation (JSDoc)
Every function and component must have a JSDoc block explaining its purpose, parameters, and return value.
### 4.4 React Patterns
- **Functional Components**: Use only functional components with hooks.
- **Fragments**: Use `` or `<>` to avoid unnecessary DOM nodes.
- **Destructuring**: Always destructure props in the component signature.
### 4.5 Clean Code Principles
- **DRY (Don't Repeat Yourself)**: Extract reusable logic into hooks or utils.
- **Single Responsibility**: One component = One section or atom.
- **No Inline Styles**: All styling must live in CSS files unless dynamic (state-driven).
---
## 5. CSS Methodology
Our approach focuses on clarity, maintainability, and visual consistency without the overhead of rigid naming frameworks.
### 5.1 Semantic Nomenclature
Use descriptive and intuitive class names that reflect the purpose of the element.
- **Sections**: Use the section name as the base class (e.g., `.hero-section`, `.services-v4`).
- **Elements**: Clear child names (e.g., `.hero-title`, `.service-card-desc`).
- **States**: Simple state markers (e.g., `.is-active`, `.has-error`).
### 5.2 Modular Scoping
Styles should be co-located or logically mapped to their respective components in `src/styles/components/`. This ensures that changes to one section don't cause side effects in another.
### 5.3 Design Token Integration
Continue to use CSS variables for all design tokens. This is non-negotiable for maintaining the "Technical Sketchbook" aesthetic across the site.
```css
.service-card {
border: 2px solid var(--primary-black);
padding: var(--spacing-md);
}
.service-card-title {
color: var(--brand-orange);
font-family: var(--font-headline);
}
```
### 5.4 Practical Nesting
Nesting is allowed for clarity but should be kept shallow to maintain performance and readability.
### 5.5 Global Utilities
Leverage global utility classes from `base.css` for cross-component aesthetics:
- `.text-textured`: For grunge/blueprint typography.
- `.blueprint-border`: For the signature 2px black border.
- `.paper-canvas`: For the textured background.
---
## 6. SEO Standards
Our goal is to position **Monch Agency** as a technical authority. This requires not only great content but perfect technical SEO execution.
### 6.1 Semantic HTML Hierarchy
Every page assembly must follow a strict heading hierarchy:
- **`
`**: Only one per page. Reserved for the main headline in the Hero section.
- **`