Monorepo folder structure

DOC-010: Monorepo Folder Structure

Estado

Approved

Contexto

MercoraHub adopta:

• Monorepo
• Turborepo
• pnpm
• NestJS
• Next.js
• Expo
• Prisma
• OpenSpec

Definido en:

• ADR-002 Package Manager
• ADR-011 Monorepo Strategy
• DOC-007 OpenSpec Project Structure

Este documento define la estructura oficial de carpetas del repositorio.

Objetivos

• Escalabilidad.
• Separación de responsabilidades.
• Reutilización.
• Integración con OpenSpec.
• Compatibilidad con agentes IA.
• Preparación para crecimiento futuro.

Estructura General

foodhub/

├── apps/
├── packages/
├── infrastructure/
├── docs/
├── packages/
│   └── api-contract/
├── agents/
├── scripts/
├── tools/
├── .github/
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

Apps

Aplicaciones desplegables.

apps/

├── api
├── web
├── help
└── mobile

apps/api

Backend NestJS.

apps/api/

├── src
├── prisma
├── test
├── Dockerfile
└── package.json

Backend Structure

src/

├── modules
├── shared
├── infrastructure
├── config
├── main.ts
└── app.module.ts

Modules

Basados en Bounded Contexts.

modules/

├── identity
├── tenants
├── locations
├── menus
├── customers
├── orders
├── billing
├── payments
├── notifications
├── analytics
├── ai
├── audit
├── feature-flags
└── integrations

Estructura de un Módulo

Ejemplo:

modules/orders/

orders/

├── application
├── domain
├── infrastructure
├── presentation
└── tests

Application Layer

application/

├── commands
├── queries
├── handlers
├── dto
└── use-cases

Domain Layer

domain/

├── entities
├── value-objects
├── events
├── repositories
└── services

Infrastructure Layer

infrastructure/

├── prisma
├── adapters
├── repositories
└── integrations

Presentation Layer

presentation/

├── controllers
├── requests
├── responses
└── mappers

apps/web

Frontend Next.js.

apps/web/

├── src
├── public
├── tests
└── package.json

apps/help

User Help Center (STORY-133) — Next.js docs portal with MDX content.

apps/help/

├── app
├── content
├── features
├── lib
├── messages
├── specs
└── package.json

Dev port 3002. Content: content/{locale}/{module}/{slug}.mdx.

apps/docs

Developer documentation portal (FEAT-080 / S-108) — Next.js + Fumadocs UI, curated content from repo docs/.

apps/docs/

├── app
├── components
├── lib
├── specs
└── package.json

Dev port 3003 (DOCS_PORT, native pnpm --filter @foodhub/docs dev). Source of truth remains git docs/; portal reads allowlisted paths via lib/source.ts + docs-content-sync gate.

Web Structure

src/

├── app
├── features
├── components
├── hooks
├── services
├── providers
├── lib
└── types

Features

Organización por dominio.

features/

├── auth
├── locations
├── menus
├── orders
├── billing
├── analytics
└── ai

apps/mobile

Aplicación Expo.

apps/mobile/

├── src
├── assets
├── tests
└── package.json

Mobile Structure

src/

├── screens
├── features
├── components
├── services
├── hooks
└── navigation

Packages

Código compartido.

packages/

├── ui
├── sdk
├── types
├── config
├── testing
├── eslint-config
└── tsconfig

Package: ui

Componentes compartidos.

packages/ui/

Contenido

Button
Input
Modal
Table
Card

Package: sdk

SDK generado desde OpenAPI.

packages/sdk/

Generado Desde

OpenAPI

Package: types

Tipos compartidos.

packages/types/

Infrastructure

Infraestructura como código.

infrastructure/

├── terraform
├── docker
├── kubernetes
└── scripts

Terraform

terraform/

├── environments
├── modules
└── shared

Environments

dev
qa
staging
prod

Docker

docker/

├── local
├── dev
└── production

Documentation

docs/

Estructura

docs/

├── adr
├── vision
├── domain
├── api
├── database
├── architecture
├── roadmap
└── backlog

Especificación

Agents

Configuración de agentes IA.

agents/

├── architect
├── backend
├── frontend
├── mobile
├── qa
├── devops
└── product

GitHub

.github/

Contenido

workflows/

pull_request_template.md

issue_templates/

Workflows

ci.yml

cd.yml

security.yml

Scripts

Automatizaciones.

scripts/

├── db
├── seed
├── migration
└── release

Tools

Herramientas auxiliares.

tools/

├── generators
├── validators
└── migrations

Prisma Structure

apps/api/prisma/

Contenido

schema.prisma

migrations/

seed.ts

Testing Structure

tests/

├── unit
├── integration
├── e2e
└── contract

Ownership

Cada módulo tendrá ownership explícito.

Ejemplo

orders

Owner:
Backend Team

Escalabilidad Futura

Esta estructura soporta:

• Modular Monolith.
• Event Driven Architecture.
• CQRS parcial.
• Extracción futura a microservicios.

Source of Truth

Arquitectura

docs/

OpenSpec

openspec/

Contrato API

packages/api-contract/

Código

apps/
packages/

Infraestructura

infrastructure/

Resultado Esperado

Esta estructura define la organización oficial del repositorio MercoraHub y establece una base escalable para desarrollo con OpenSpec, agentes IA y un equipo de ingeniería en crecimiento.

Próximos Documentos Recomendados

Una vez completados los DOC-001 al DOC-010, recomiendo crear:

DOC-011 Product Requirements Document (PRD)

DOC-012 UX/UI Guidelines

DOC-013 OpenAPI Specification

DOC-014 Prisma Schema

DOC-015 Event Bus Implementation

DOC-016 Release Management

Fin de la Fase Foundation

Con DOC-001 a DOC-010 queda definida la fundación completa del producto MercoraHub:

• Visión
• Dominio
• Arquitectura
• Base de datos
• APIs
• Backlog
• Roadmap
• OpenSpec
• Monorepo

Lista para iniciar implementación.