# tiendanube/tiendanube-app-native-template-node architecture

> Architecture diagram of the GitHub repository tiendanube/tiendanube-app-native-template-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiendanube/tiendanube-app-native-template-node
- Repository: https://github.com/tiendanube/tiendanube-app-native-template-node

## Overview

##### Project type and purpose
- This is a full-stack monorepo template for building Nuvemshop integrated apps.
- “api” is a Node.js + Express + TypeScript backend that handles authentication, communicates with Nuvemshop’s Auth and Product APIs, and exposes your own REST endpoints.
- “frontend” is a React (Vite) app that provides the UI and calls your backend.

##### File structure
- Top level:
- .yarn, yarnrc.yml → Yarn Plug’n’Play workspaces
- api/ → backend code, with its own Yarn setup
- frontend/ → React app (monorepo workspace)
- api/:
- src/config → Express setup, routes, Nuvemshop API client configs
- src/features → feature modules (auth, product) organized in controller-service-interface structure
- src/middlewares → request validation, error handling
- src/repository → data persistence (e.g., UserRepository)
- src/utils → exception classes, Passport strategy, HTTP codes
- README cues: uses Passport for OAuth, integrates with Nuvemshop Auth/Product, no local DB by default (db.example.json for sample).
- frontend/: standard React/Vite project linking to api via HTTP calls.

##### Key insights from README
- Two main pieces: authentication flow (install app on a Nuvemshop store → OAuth flow → store tokens) and product operations (list/create/delete via Nuvemshop API).
- Ports: default frontend localhost:5173, backend via start:api (likely localhost:3000).

##### Main components
a. Frontend (React/Vite)
b. Backend API (Node.js/Express/TypeScript)
c. External Nuvemshop Services (Auth API, Product API)
d. (Optional) Token Store / Persistence (in-memory or JSON mock)

##### Relationships and data flows
- Frontend → HTTP(S) → Backend REST endpoints
- Backend → OAuth handshake → Nuvemshop Auth API
- Backend → REST calls → Nuvemshop Product API
- Backend middleware (Passport strategy) secures routes
- Repository layer → stores/retrieves user tokens (mock JSON or real DB)

##### Architectural patterns & design principles
- Monorepo with Yarn Workspaces: api and frontend share tooling.
- Modular “features” structure in backend → follows MVC-inspired layering:
- Controller → routes
- Service → business logic
- Repository → data access
- Interfaces → strict TypeScript contracts
- Middleware chain for cross-cutting concerns (auth check, error handling).
- Separation of concerns: UI vs API vs external third-party services.

##### Technologies, frameworks, libraries
- Frontend: React, Vite, Yarn
- Backend: Node.js, Express, TypeScript, Passport (OAuth), Yarn, nodemon
- External: Nuvemshop API clients (tiendanube-api.client.ts, tiendanube-auth.client.ts)

- [ ] Frontend container with pages/components → calls /api/** endpoints
- [ ] Backend container subdivided into layers (config, features, middleware, repository, utils)
- [ ] External Nuvemshop Auth and Product APIs
- [ ] Notes on Yarn workspace linking

## Diagram (Mermaid)

```mermaid
flowchart TD
    FE["Frontend (React/Vite)"]:::frontend
    FE -->|"HTTP calls /api/*"| BEENTRY

    subgraph "Backend API (Node.js/Express/TypeScript)"
        BEENTRY["api/src/index.ts"]:::backend

        subgraph "Config"
            CONF["config/index.ts"]:::config
            ROUTES["config/routes.ts"]:::config
            AUTHCLIENT["tiendanube-auth.client.ts"]:::config
            PRODCLIENT["tiendanube-api.client.ts"]:::config
        end

        subgraph "Middlewares"
            M1["before-check-client.middleware.ts"]:::middleware
            M2["check-user-credentials.middleware.ts"]:::middleware
            M3["error-handling.middleware.ts"]:::middleware
        end

        subgraph "Features"
            subgraph "Auth Feature"
                ACTRL["auth.controller.ts"]:::feature
                ASVC["auth.service.ts"]:::feature
                INSTALL["install-app.service.ts"]:::feature
                AINTF["interfaces/*.ts"]:::feature
            end
            subgraph "Product Feature"
                PCTRL["product.controller.ts"]:::feature
                PSVC["product.service.ts"]:::feature
                PMOCK["__mock__/product.mock.ts"]:::feature
                PINTF["interface/product.interface.ts"]:::feature
            end
        end

        subgraph "Repository"
            REPO["UserRepository.ts"]:::repo
        end

        subgraph "Utils"
            STRAT["passport-strategy.ts"]:::util
            HTTPERR["HttpErrorException.ts"]:::util
            SCODE["statusCode.enum.ts"]:::util
        end

        subgraph "Typings"
            TYP["express/index.d.ts"]:::typings
        end

        DB["db.example.json"]:::db

        BEENTRY --> CONF
        CONF --> ROUTES
        ROUTES --> M1
        ROUTES --> M2
        ROUTES --> ACTRL
        ROUTES --> PCTRL
        ACTRL --> ASVC
        ACTRL --> INSTALL
        PCTRL --> PSVC
        ASVC --> AUTHCLIENT
        INSTALL --> AUTHCLIENT
        PSVC --> PRODCLIENT
        ASVC --> REPO
        PSVC --> REPO
        REPO --> DB
        ASVC --> STRAT
        ASVC --> HTTPERR
        ASVC --> SCODE
        BEENTRY --> M3
    end

    ExternalAuth["Nuvemshop Auth API"]:::external
    ExternalProd["Nuvemshop Product API"]:::external

    AUTHCLIENT -->|"OAuth flow"| ExternalAuth
    PRODCLIENT -->|"REST CRUD"| ExternalProd

    click FE "https://github.com/tiendanube/tiendanube-app-native-template-node/tree/main/frontend/"
    click BEENTRY "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/index.ts"
    click CONF "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/config/index.ts"
    click ROUTES "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/config/routes.ts"
    click AUTHCLIENT "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/config/tiendanube-auth.client.ts"
    click PRODCLIENT "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/config/tiendanube-api.client.ts"
    click ACTRL "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/auth/auth.controller.ts"
    click ASVC "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/auth/auth.service.ts"
    click INSTALL "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/auth/install-app.service.ts"
    click AINTF "https://github.com/tiendanube/tiendanube-app-native-template-node/tree/main/api/src/features/auth/interfaces"
    click PCTRL "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/product/product.controller.ts"
    click PSVC "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/product/product.service.ts"
    click PMOCK "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/product/__mock__/product.mock.ts"
    click PINTF "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/features/product/interface/product.interface.ts"
    click REPO "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/repository/UserRepository.ts"
    click M1 "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/middlewares/before-check-client.middleware.ts"
    click M2 "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/middlewares/check-user-credentials.middleware.ts"
    click M3 "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/middlewares/error-handling.middleware.ts"
    click STRAT "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/utils/passaport-strategy.ts"
    click HTTPERR "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/utils/HttpErrorException.ts"
    click SCODE "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/utils/statusCode.enum.ts"
    click TYP "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/src/typings/express/index.d.ts"
    click DB "https://github.com/tiendanube/tiendanube-app-native-template-node/blob/main/api/db.example.json"

    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef config fill:#afa,stroke:#333,stroke-width:1px
    classDef middleware fill:#ffa,stroke:#333,stroke-width:1px
    classDef feature fill:#8f8,stroke:#333,stroke-width:1px
    classDef repo fill:#dfd,stroke:#333,stroke-width:1px
    classDef util fill:#fcf,stroke:#333,stroke-width:1px
    classDef typings fill:#cff,stroke:#333,stroke-width:1px
    classDef db fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
```
