feat(architecture): add complete technical architecture for SimpleNote
- ARCHITECTURE.md: main architecture document - api-spec.yaml: full OpenAPI 3.0 spec - folder-structure.md: detailed folder layout - data-format.md: JSON schemas for .meta.json, .library.json, .tag-index.json - env-template.md: environment variables documentation - cli-protocol.md: CLI-to-API communication protocol
This commit is contained in:
Bulma
170
folder-structure.md
Normal file
170
folder-structure.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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/
|
||||
```
|
||||
Reference in New Issue
Block a user