How miguelrivero/document_list works
Project type and purpose
• This is a full-stack, real-time document-management application.
• Frontend: framework-less TypeScript + Sass using clean-architecture/DDD principles.
• Backend: Go service exposing REST endpoints and a WebSocket for live updates.
High-level file-structure analysis
• Top-level:
• package.json, tsconfig.json, vite.config.ts – frontend build & config
• src/ – frontend source, organized by layers (application, domain, infrastructure, ui, utils)
• server/ – Go backend with server.go, go.mod, README
• Layers in src/:
• application/DocumentService.ts – orchestrates use-cases
• domain/Document.ts & DocumentMapper.ts – entities & mapping
• infrastructure/DocumentApi.ts & DocumentWebSocket.ts – network adapters
• ui/ – UI components, state management, styles
• utils/ – shared helpers
• Tests are alongside features and use Vitest/Jest configs.
README insights
• Emphasis on “no framework,” modularity, maintainability, and real-time updates.
• Two sync modes (merge vs replace) implemented in DocumentStore.
• Sass partials and modular components for UI.
Main components & boundaries (to include
A. Actor
• End-User (Browser)
B. Frontend Container (runs in browser)
1. UI Layer (src/ui)
– Components: DocumentList, DocumentForm, AddDocumentModal, NotificationBanner
– Styles: Sass modules (partials & component styles)
2. State Layer (src/ui/state)
– DocumentStore (handles merge/replace modes)
3. Application Layer (src/application)
– DocumentService (business use-cases: fetch, add, sync)
4. Domain Layer (src/domain)
– Document entity, DocumentMapper
5. Infrastructure Layer (src/infrastructure)
– DocumentApi (HTTP calls: GET/POST /documents)
– DocumentWebSocket (WebSocket client for real-time updates)
6. Utility Layer (src/utils)
– Helpers (domHelpers, formatRelativeTime, sortSemver, fillAndSubmitForm)
C. Backend Container (server/server.go)
• HTTP REST API (e.g., GET /documents, POST /documents)
• WebSocket endpoint (push notifications on changes)
• (Potential) Data store or in-memory list
D. External/Infrastructure Services
• Browser local runtime
• Dev tools: Vite dev server (npm run dev)
• Vitest/Jest for tests (unit & integration)
Relationships & data flows
• Browser → UI Layer: user clicks “Add” or views list
• UI Layer → DocumentStore: dispatch actions (add, init)
• DocumentStore → DocumentService: calls business methods
• DocumentService → Infrastructure
• DocumentApi (HTTP fetch/save)
• DocumentWebSocket (subscribe to real-time updates)
• DocumentService → DomainMapper: map raw API payloads to Document entities
• DocumentStore updates subscribers (UI components)
• Backend → Browser over WebSocket: sends notifications of new documents
• Browser → Backend over HTTP: fetch initial list, post new documents
Architectural patterns & design principles
• Layered/Clean Architecture: UI ↔ State ↔ Application ↔ Domain ↔ Infrastructure
• Domain-Driven Design: clear Entity/Mapper in domain
• Dependency Inversion: higher layers depend on abstractions (interfaces in infrastructure)
• Real-time sync strategy: merge vs replace modes in store
• Modular CSS: Sass partials per component