En este espacio se especifican todos los estándares que sigue el proyecto para tener una correcta y clara estructura tanto a nivel código como en el repositorio y documentación.
Monorepo con dos workspaces claramente delimitados. La raíz del repo es punto de entrada para el evaluador.
ai-dev-summit/ │ ├── README.md ← Entry point: descripción + setup + link Notion ├── .gitignore │ ├── frontend/ ← React JS · Vite │ ├── public/ │ │ └── assets/ │ │ └── gallery/ ← Imágenes estáticas del evento │ ├── src/ │ │ ├── config/ │ │ │ └── event.config.ts │ │ ├── hooks/ │ │ │ └── useCountdown.ts │ │ ├── services/ │ │ │ └── registration.service.ts │ │ ├── components/ │ │ │ ├── layout/ │ │ │ │ └── NavBar.tsx │ │ │ ├── sections/ │ │ │ │ ├── HeroSection.tsx │ │ │ │ ├── EventInfoSection.tsx │ │ │ │ ├── GallerySection.tsx │ │ │ │ └── RegistrationSection.tsx │ │ │ ├── countdown/ │ │ │ │ └── CountdownTimer.tsx │ │ │ └── form/ │ │ │ ├── RegistrationForm.tsx │ │ │ └── FormField.tsx │ │ ├── styles/ │ │ │ ├── globals.css ← CSS variables (design tokens) │ │ │ └── animations.css ← Keyframes reutilizables │ │ └── App.tsx │ ├── index.html │ ├── vite.config.ts │ ├── tsconfig.json │ └── package.json │ └── backend/ ← Python · FastAPI ├── app/ │ ├── main.py │ ├── config.py │ ├── api/ │ │ └── v1/ │ │ └── registrations.py │ ├── schemas/ │ │ └── registration.py │ ├── services/ │ │ └── registration.py │ ├── models/ │ │ └── registration.py │ └── db/ │ ├── base.py │ └── session.py ├── alembic/ │ ├── env.py │ └── versions/ │ └── 001_create_registrations_table.py ├── .env.example ├── requirements.txt └── alembic.ini
Los nombres deben ser auto-documentados, es decir que al leer un nombre, debe quedar claro qué es, qué hace y a qué capa pertenece, sin necesitar leer su implementación.
Archivos y carpetas
| Tipo | Convención | Ejemplo |
|---|---|---|
| Componentes React | PascalCase + sufijo de tipo |
HeroSection.tsx, FormField.tsx |
| Hooks | camelCase con prefijo use |
useCountdown.ts |
| Services | camelCase con sufijo .service |
registration.service.ts |
| Config | camelCase con sufijo .config |
event.config.ts |
| Estilos | kebab-case |
globals.css, animations.css |
| Carpetas | kebab-case |
sections/, countdown/ |
Variables y funciones
| Tipo | Convención | Ejemplo |
|---|---|---|
| Variables reactivas | camelCase |
remainingMs, isExpired, submitStatus |
| Handlers de eventos | camelCase con prefijo handle |
handleSubmit, handleFieldChange |
| Booleanos | camelCase con prefijo is/has/can |
isExpired, isLoading, hasError |
| Constantes de config | SCREAMING_SNAKE_CASE |
EVENT_TITLE, COUNTDOWN_DURATION_MS |
| Tipos e interfaces | PascalCase |
CountdownConfig, RegistrationPayload |
| Enums de estado | PascalCase |
SubmitStatus.Idle, SubmitStatus.Loading |
CSS
| Tipo | Convención | Ejemplo |
|---|---|---|
| Variables CSS (design tokens) | --kebab-case con prefijo de categoría |
--color-primary, --spacing-lg, --font-size-heading |
| Clases de componente | kebab-case con prefijo de componente |
.hero-section, .countdown-timer, .form-field |
| Clases de estado | kebab-case con prefijo is- |
.is-expired, .is-loading, .is-visible |
| Keyframes | camelCase |
@keyframes fadeSlideUp, @keyframes fadeOut |
Archivos y módulos
| Tipo | Convención | Ejemplo |
|---|---|---|
| Módulos Python | snake_case |
registration.py, session.py |
| Carpetas/paquetes | snake_case |
api/, schemas/, services/ |
| Migraciones Alembic | NNN_snake_case_description |
001_create_registrations_table.py |
Python — código
| Tipo | Convención | Ejemplo |
|---|---|---|
| Variables y funciones | snake_case |
registered_at, get_db, create_registration |
| Clases | PascalCase |
Registration, RegistrationCreate, RegistrationResponse |
| Constantes | SCREAMING_SNAKE_CASE |
DATABASE_URL, ALLOWED_ORIGINS |
| Schemas Pydantic | PascalCase con sufijo de intención |
RegistrationCreate (input) · RegistrationResponse (output) |
| Modelos ORM | PascalCase singular |
Registration |
| Router prefix | kebab-case |
/api/v1/registrations |