rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1376d3e4f0cd0af894eeb96545c32c4be3ec8301
mercadodevida/project/CAVEMAN.md
chattie d595b4871f feat(ADM-018): completed feature
2026-08-17 22:23:10 +02:00

7.9 KiB
Raw Blame History

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