# miguelrivero/document_list architecture

> Architecture diagram of the GitHub repository miguelrivero/document_list, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miguelrivero/document_list
- Repository: https://github.com/miguelrivero/document_list

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    EndUser((End-User Browser)):::actor

    subgraph "Frontend App"
        subgraph "UI Layer"
            DL["DocumentList"]:::ui
            DF["DocumentForm"]:::ui
            AM["AddDocumentModal"]:::ui
            NB["NotificationBanner"]:::ui
        end
        subgraph "State Layer"
            DS["DocumentStore"]:::state
        end
        subgraph "Application Layer"
            SVC["DocumentService"]:::app
        end
        subgraph "Domain Layer"
            DM["DocumentMapper"]:::domain
            DOC["Document"]:::domain
        end
        subgraph "Infrastructure Layer"
            API["DocumentApi"]:::infra
            WS["DocumentWebSocket"]:::infra
        end
        subgraph "Utility Layer"
            UH["domHelpers"]:::util
            TF["formatRelativeTime"]:::util
            SV["sortSemver"]:::util
            FH["fillAndSubmitForm"]:::util
        end
    end

    subgraph "Backend Service"
        BSRV["server.go"]:::backend
        MOD["go.mod"]:::backend
        RMD["README.md"]:::backend
    end

    EndUser -->|"clicks"| DL
    EndUser -->|"clicks"| DF
    EndUser -->|"clicks"| AM
    EndUser -->|"receives notifications"| NB

    DL -->|"dispatch action"| DS
    DF -->|"dispatch action"| DS
    AM -->|"dispatch action"| DS
    NB -->|"dispatch action"| DS

    DS -->|"calls use-case"| SVC

    SVC -->|"GET /documents\nPOST /documents"| API
    SVC -->|"WS subscribe"| WS
    SVC -->|"map payload"| DM

    DM -->|"entity"| DOC

    API -->|"HTTP"| BSRV
    WS -->|"WebSocket"| BSRV
    BSRV -->|"notifyNewDoc"| WS

    click DL "https://github.com/miguelrivero/document_list/blob/main/src/ui/components/DocumentList.ts"
    click DF "https://github.com/miguelrivero/document_list/blob/main/src/ui/components/DocumentForm.ts"
    click AM "https://github.com/miguelrivero/document_list/blob/main/src/ui/components/AddDocumentModal.ts"
    click NB "https://github.com/miguelrivero/document_list/blob/main/src/ui/components/NotificationBanner.ts"
    click DS "https://github.com/miguelrivero/document_list/blob/main/src/ui/state/DocumentStore.ts"
    click SVC "https://github.com/miguelrivero/document_list/blob/main/src/application/DocumentService.ts"
    click DOC "https://github.com/miguelrivero/document_list/blob/main/src/domain/Document.ts"
    click DM "https://github.com/miguelrivero/document_list/blob/main/src/domain/DocumentMapper.ts"
    click API "https://github.com/miguelrivero/document_list/blob/main/src/infrastructure/DocumentApi.ts"
    click WS "https://github.com/miguelrivero/document_list/blob/main/src/infrastructure/DocumentWebSocket.ts"
    click UH "https://github.com/miguelrivero/document_list/blob/main/src/utils/domHelpers.ts"
    click TF "https://github.com/miguelrivero/document_list/blob/main/src/utils/formatRelativeTime.ts"
    click SV "https://github.com/miguelrivero/document_list/blob/main/src/utils/sortSemver.ts"
    click FH "https://github.com/miguelrivero/document_list/blob/main/src/utils/fillAndSubmitForm.ts"
    click BSRV "https://github.com/miguelrivero/document_list/blob/main/server/server.go"
    click MOD "https://github.com/miguelrivero/document_list/blob/main/server/go.mod"
    click RMD "https://github.com/miguelrivero/document_list/blob/main/server/README.md"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef state fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef app fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef domain fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef infra fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef backend fill:#E0E0E0,stroke:#333,stroke-width:1px;
    classDef actor fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
```
