simplenote-web/folder-structure.md

# SimpleNote - Estructura de Carpetas

## Estructura General del Repositorio

```
simplenote-web/
├── src/
│   ├── index.js                 # Entry point (bind port, listen)
│   ├── app.js                   # Express app setup, middleware, routes
│   ├── config/
│   │   └── index.js             # Env vars loader y defaults
│   ├── routes/
│   │   ├── index.js             # Router principal (mount /api/v1/*)
│   │   ├── documents.js         # /documents routes
│   │   ├── libraries.js        # /libraries routes
│   │   ├── tags.js              # /tags routes
│   │   └── auth.js              # /auth routes
│   ├── services/
│   │   ├── documentService.js   # Lógica de documentos
│   │   ├── libraryService.js    # Lógica de librerías
│   │   └── tagService.js        # Lógica de tags e indexación
│   ├── middleware/
│   │   ├── auth.js              # Middleware de autenticación Bearer
│   │   └── errorHandler.js      # Handler global de errores
│   ├── utils/
│   │   ├── markdown.js          # Parseo y serialización de Markdown
│   │   ├── fsHelper.js          # Helpers de filesystem (safe paths, etc)
│   │   ├── uuid.js              # Wrapper de uuid/v4
│   │   └── errors.js            # Clases de errores custom (NotFound, etc)
│   └── indexers/
│       └── tagIndexer.js        # Rebuild y query del .tag-index.json
├── data/                        # Raíz de documentos (DATA_ROOT)
│   ├── .tag-index.json          # Índice global de tags
│   ├── .auth-tokens.json        # Tokens de API válidos
│   └── libraries/
│       └── {uuid}/
│           ├── .library.json
│           ├── documents/
│           │   └── {uuid}/
│           │       ├── index.md
│           │       └── .meta.json
│           └── sub-libraries/
│               └── {child-uuid}/...
├── tests/
│   ├── unit/
│   │   ├── services/
│   │   │   ├── documentService.test.js
│   │   │   ├── libraryService.test.js
│   │   │   └── tagService.test.js
│   │   └── utils/
│   │       └── markdown.test.js
│   └── integration/
│       └── api.test.js
├── scripts/
│   └── init-data.js             # Script de inicialización (crea default lib)
├── package.json
├── .env.example
└── README.md

simplenote-cli/
├── src/
│   ├── index.js                 # Entry point (Commander program)
│   ├── api/
│   │   └── client.js            # SimpleNoteClient (axios-based)
│   ├── commands/
│   │   ├── index.js             # Registra todos los subcommands
│   │   ├── doc.js               # simplenote doc <subcmd>
│   │   ├── lib.js               # simplenote lib <subcmd>
│   │   └── tag.js               # simplenote tag <subcmd>
│   └── config/
│       ├── loader.js            # Carga ~/.config/simplenote/config.json
│       └── errors.js            # Errores CLI custom
├── package.json
└── README.md
```

## Estructura de Datos en Disco (DATA_ROOT)

```
data/                                    # DATA_ROOT (default: ./data)
├── .tag-index.json                      # Tag index global
├── .auth-tokens.json                    # Auth tokens
└── libraries/
    └── {library-uuid}/
        ├── .library.json
        ├── documents/
        │   └── {doc-uuid}/
        │       ├── index.md            # Contenido Markdown
        │       └── .meta.json          # Metadata (tags, timestamps)
        └── sub-libraries/
            └── {child-uuid}/
                ├── .library.json
                └── documents/
                    └── ... (recursivo)
```

## Archivos de Metadata

### `.library.json` (por librería)
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Backend Requirements",
  "parentId": null,
  "path": "libraries/550e8400",
  "createdAt": "2026-03-28T09:00:00Z",
  "updatedAt": "2026-03-28T09:00:00Z"
}
```

### `.meta.json` (por documento)
```json
{
  "id": "550e8401-e29b-41d4-a716-446655440001",
  "title": "API Authentication",
  "tags": ["backend", "api", "auth"],
  "type": "requirement",
  "status": "draft",
  "priority": "high",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "agent-001",
  "createdAt": "2026-03-28T10:00:00Z",
  "updatedAt": "2026-03-28T10:00:00Z"
}
```

### `index.md` (contenido)
```markdown
---
id: REQ-001
title: API Authentication
type: requirement
priority: high
status: draft
tags: [backend, api, auth]
createdBy: agent-001
createdAt: 2026-03-28
---

# API Authentication

## Descripción
El sistema debe soportar autenticación via tokens Bearer.

## Criterios de Aceptación
- [ ] Endpoint POST /api/auth/token
- [ ] Middleware valida Bearer token
- [ ] Retorna 401 si token inválido
```

## Archivos de Configuración Local (CLI)

```
~/.config/simplenote/
└── config.json                        # Config CLI local
    {
      "apiUrl": "http://localhost:3000/api/v1",
      "token": "snk_xxxxx",
      "activeLibrary": "default"
    }
```

## Archivos de Configuración del Servidor

```
simplenote-web/
├── .env.example                       # Template de variables de entorno
├── .env                               # No commitear (contiene secrets)
└── .gitignore                         # Ignora .env, data/, node_modules/
```