feat(ADM-018): completed feature
This commit is contained in:
chattie
248
project/CAVEMAN.md
Normal file
248
project/CAVEMAN.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# MercadoDeVida vNext — Caveman Architecture
|
||||
|
||||
> SIMPLE CODE. CLEAR MODULES. SMALL CHANGES. NO MAGIC.
|
||||
|
||||
---
|
||||
|
||||
# 0. CORE PHILOSOPHY
|
||||
|
||||
Build boring software. Boring = good.
|
||||
|
||||
Prefer: simple code, explicit dependencies, small modules, clear APIs, strong typing, predictable behavior, easy testing, easy replacement, easy debugging.
|
||||
|
||||
Avoid: clever abstractions, unnecessary microservices, circular dependencies, global state, giant service classes, framework magic.
|
||||
|
||||
The system must be easy for humans AND AI agents to understand.
|
||||
|
||||
---
|
||||
|
||||
# 1. ARCHITECTURE
|
||||
|
||||
**Modular Monolith** — each business domain is an isolated module.
|
||||
|
||||
```
|
||||
src/
|
||||
├── modules/
|
||||
│ ├── auth/ # Identity module (sessions, login, register)
|
||||
│ ├── users/ # User profiles
|
||||
│ ├── catalog/ # Products, variants, attributes
|
||||
│ ├── categories/ # Category taxonomy
|
||||
│ ├── brands/ # Brand management
|
||||
│ ├── pricing/ # Price calculation + VAT
|
||||
│ ├── promotions/ # Discounts, promo codes
|
||||
│ ├── inventory/ # Stock management
|
||||
│ ├── cart/ # Shopping cart
|
||||
│ ├── checkout/ # Checkout orchestrator
|
||||
│ ├── orders/ # Order management
|
||||
│ ├── payments/ # Payment provider interface
|
||||
│ ├── shipping/ # Shipping zones and methods
|
||||
│ ├── seo/ # SEO metadata
|
||||
│ ├── cms/ # Content management
|
||||
│ ├── reviews/ # Product reviews
|
||||
│ ├── notifications/ # Email/push notifications
|
||||
│ ├── cache/ # Caching layer
|
||||
│ ├── security/ # Rate limiting, audit log, MFA
|
||||
│ ├── observability/ # Traces, metrics
|
||||
│ └── flags/ # Feature flags
|
||||
├── shared/
|
||||
├── infrastructure/
|
||||
└── app/
|
||||
```
|
||||
|
||||
Modules communicate through: (1) explicit public interfaces, (2) domain/application events, (3) typed contracts. Never access another module's internal implementation.
|
||||
|
||||
---
|
||||
|
||||
# 2. MODULE RULE
|
||||
|
||||
Every module owns its logic. Structure:
|
||||
|
||||
```
|
||||
modules/<name>/
|
||||
├── domain/ # Pure business rules. No DB, no HTTP, no framework.
|
||||
├── application/ # Use cases: CreateProduct, ReserveStock, CreateOrder
|
||||
├── infrastructure/ # PostgreSQL, Redis, Stripe, Email adapters
|
||||
├── api/ # Thin HTTP controllers
|
||||
├── tests/ # Unit + boundary tests
|
||||
└── index.ts # Public API only
|
||||
```
|
||||
|
||||
Controllers must be thin: request → validate → use case → response. NO business logic in controllers.
|
||||
|
||||
---
|
||||
|
||||
# 3. SDD IS MANDATORY
|
||||
|
||||
**NO FEATURE STARTS WITH CODE.** Every change starts with a specification.
|
||||
|
||||
Directory: `specs/<feature>/`
|
||||
|
||||
Each feature gets:
|
||||
|
||||
- `SPEC.md` — Problem, Goal, User story, Functional requirements, Acceptance criteria
|
||||
- `DESIGN.md` — Affected modules, new interfaces, API changes, DB changes, events
|
||||
- `TASKS.md` — Small atomic tasks
|
||||
- `TESKS.md` — Required tests
|
||||
- Optional: `ADR.md`, `MIGRATION.md`, `ROLLBACK.md`
|
||||
|
||||
---
|
||||
|
||||
# 4. TECH STACK
|
||||
|
||||
## Frontend
|
||||
|
||||
- **Next.js + React + TypeScript + Tailwind CSS**
|
||||
- Server Components where useful
|
||||
- SSR/SSG for SEO-sensitive pages
|
||||
- Client-side only where interaction requires it
|
||||
|
||||
## Backend
|
||||
|
||||
- TypeScript + Node.js + Fastify
|
||||
- Strict module boundaries
|
||||
- PostgreSQL (primary database)
|
||||
- Redis (cache, sessions, rate limiting — NOT source of truth)
|
||||
|
||||
## Observability
|
||||
|
||||
- Structured logs, metrics, traces
|
||||
- OpenTelemetry-compatible interfaces
|
||||
- Per-module metrics
|
||||
|
||||
---
|
||||
|
||||
# 5. DATABASE RULES
|
||||
|
||||
Database belongs to modules. Logical ownership must remain clear.
|
||||
|
||||
Naming: `<module>_<entity>` — e.g., `catalog_products`, `orders_orders`, `inventory_stock`.
|
||||
|
||||
Never let random modules query arbitrary tables. Access data through module interfaces only.
|
||||
|
||||
---
|
||||
|
||||
# 6. CORE BUSINESS RULES
|
||||
|
||||
- **Catalog ≠ Inventory**: Catalog answers "what is this product?"; Inventory answers "can I sell it?"
|
||||
- **Cart ≠ Checkout**: Cart stores items; Checkout validates, calculates, orchestrates
|
||||
- **Checkout is orchestrator**: coordinates cart, pricing, inventory, shipping, orders, payments
|
||||
- **Orders are historical**: snapshot product name, SKU, EAN, prices, taxes at creation time
|
||||
- **Payment provider behind interface**: StripePaymentProvider, RedsysPaymentProvider — domain never imports Stripe SDK directly
|
||||
- **Backend calculates everything**: never trust price, stock, discount, total from frontend
|
||||
- **Idempotency everywhere**: checkout, webhooks, payment operations
|
||||
|
||||
---
|
||||
|
||||
# 7. SEO IS CORE BUSINESS LOGIC
|
||||
|
||||
Support: canonical URLs, structured data (Product, Breadcrumb, Organization schema), sitemap.xml, robots.txt, OpenGraph, metadata per page.
|
||||
|
||||
URLs: `/productos/<slug>`, `/categoria/<slug>`, `/marca/<slug>`.
|
||||
|
||||
---
|
||||
|
||||
# 8. CAVEMAN RULES
|
||||
|
||||
```
|
||||
ONE MODULE = ONE JOB
|
||||
ONE USE CASE = ONE PURPOSE
|
||||
DATABASE = SOURCE OF TRUTH
|
||||
REDIS = CACHE, NOT TRUTH
|
||||
CONTROLLER = THIN
|
||||
BUSINESS LOGIC = DOMAIN
|
||||
EXTERNAL API = ADAPTER
|
||||
NO CROSS-MODULE TABLE QUERIES
|
||||
NO GLOBAL STATE
|
||||
NO HIDDEN MAGIC
|
||||
NO COPY-PASTE BUSINESS LOGIC
|
||||
NO FEATURE WITHOUT SPEC
|
||||
NO DATABASE CHANGE WITHOUT MIGRATION
|
||||
NO CRITICAL LOGIC WITHOUT TEST
|
||||
NO EXTERNAL EVENT WITHOUT IDEMPOTENCY
|
||||
NO PAYMENT TRUST FROM FRONTEND
|
||||
NO PRICE TRUST FROM FRONTEND
|
||||
NO BIG REWRITE
|
||||
SMALL CHANGE
|
||||
TEST CHANGE
|
||||
SHIP CHANGE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 9. FRONTEND STRUCTURE (to be built)
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── app/ # Next.js App Router pages
|
||||
│ │ ├── (shop)/ # Shop routes (product, category, brand, search)
|
||||
│ │ ├── (checkout)/ # Cart + checkout flow
|
||||
│ │ ├── (account)/ # User account, orders
|
||||
│ │ ├── (admin)/ # Admin panel (protected)
|
||||
│ │ └── api/ # API routes
|
||||
│ ├── components/ # Shared UI components
|
||||
│ │ ├── ui/ # Base components (Button, Input, Card...)
|
||||
│ │ ├── product/ # Product-specific components
|
||||
│ │ ├── cart/ # Cart components
|
||||
│ │ └── layout/ # Header, Footer, Nav
|
||||
│ ├── modules/ # Module-specific frontend code (mirrors backend modules)
|
||||
│ ├── lib/ # Utilities, API client, types
|
||||
│ └── styles/
|
||||
├── public/
|
||||
└── tests/
|
||||
├── unit/
|
||||
├── integration/
|
||||
└── e2e/
|
||||
```
|
||||
|
||||
**Pages to build (Frontend v1):**
|
||||
|
||||
1. Homepage — Hero, featured products, categories, brand highlights
|
||||
2. Category page — Product listing with filters, pagination, SEO metadata
|
||||
3. Product detail page — Images, description, nutrition, reviews, add to cart
|
||||
4. Brand page — Brand info + brand products
|
||||
5. Search results page — Search with filters
|
||||
6. Cart page — Cart items, totals, promo code
|
||||
7. Checkout — Address, shipping, payment, order summary
|
||||
8. Order confirmation — Order details, next steps
|
||||
9. User account — Profile, orders history, addresses
|
||||
10. Admin panel — Product CRUD, order management, CMS
|
||||
|
||||
---
|
||||
|
||||
# 10. FRONTEND-BACKEND COMMUNICATION
|
||||
|
||||
Frontend communicates with backend via:
|
||||
|
||||
1. **Server Components** (SSR): Direct DB queries through Prisma/Postgres (same DB, no HTTP overhead)
|
||||
2. **Server Actions**: Form submissions, mutations (type-safe, no REST overhead)
|
||||
3. **API Routes** (minimal): External integrations, webhooks, special cases
|
||||
|
||||
Never call backend REST API from client components. Use Server Components and Server Actions.
|
||||
|
||||
---
|
||||
|
||||
# 11. TESTING PYRAMID
|
||||
|
||||
- **Unit tests**: Business rules in domain/application layers — many
|
||||
- **Integration tests**: Repositories against real DB, API endpoints — some
|
||||
- **E2E tests**: Critical flows — few
|
||||
|
||||
Critical E2E flows: register → login → search → view product → add to cart → checkout → payment → order confirmation
|
||||
|
||||
---
|
||||
|
||||
# 12. DEFINITION OF DONE
|
||||
|
||||
A feature is DONE when:
|
||||
|
||||
- SPEC.md complete with testable acceptance criteria
|
||||
- DESIGN.md reviewed and approved
|
||||
- Implementation complete (smallest possible change)
|
||||
- Unit + integration tests passing
|
||||
- Security reviewed
|
||||
- Observability added (logs/metrics)
|
||||
- Documentation updated
|
||||
- Migration tested
|
||||
- Rollback possible
|
||||
- Acceptance criteria verified against spec
|
||||
Reference in New Issue
Block a user