Lynkedup-Node-Backend/best_practices.md

📘 Project Best Practices

1. Project Purpose

LynkedUp is a mobile-first, SDK-driven application suite with enterprise-grade security and offline-first capabilities. It is structured as a PNPM monorepo orchestrated by Nx, providing modular Core SDKs (security, storage, sync, policy, trust) and Feature SDKs (auth, tasks, messaging, etc.) consumed by React Native apps and a Node.js GraphQL BFF.

2. Project Structure

• Monorepo
  • apps/
    • lynkedup-pro/ and lynkedup-foundation/: React Native apps demonstrating SDK composition.
    • api-bff/: Node.js Fastify + Apollo GraphQL Backend For Frontend.
    • sdk-playground/: Development sandbox for SDKs.
  • packages/
    • core/: Tier-0 infrastructure SDKs (e.g., security, storage, sync, policy-client, runtime, trust).# 📘 Project Best Practices

1. Project Purpose

LynkedUp is a mobile-first, SDK-driven application suite with enterprise-grade security and offline-first capabilities. It is structured as a PNPM monorepo orchestrated by Nx, providing modular Core SDKs (security, storage, sync, policy, trust) and Feature SDKs (auth, tasks, messaging, etc.) consumed by React Native apps and a Node.js GraphQL BFF.

2. Project Structure

• Monorepo

  • apps/
    • lynkedup-pro/ and lynkedup-foundation/: React Native apps demonstrating SDK composition.
    • api-bff/: Node.js Fastify + Apollo GraphQL Backend For Frontend.
    • sdk-playground/: Development sandbox for SDKs.
  • packages/
    • core/: Tier-0 infrastructure SDKs (e.g., security, storage, sync, policy-client, runtime, trust).
    • feature-*/: Tier-1 feature SDKs following clean architecture (domain, data, ui-rn).
    • shared/: Common types, config, and UI kit.
  • Tooling & Config: Nx, ESLint, Prettier, Changesets, Commitlint.

• Separation of concerns (Clean Architecture conventions)

  • Feature SDKs:
    • domain/: Pure business logic (use cases, entities, interfaces). No platform or infra dependencies.
    • data/: Repositories/adapters that implement domain interfaces and talk to core SDKs and BFF.
    • ui-rn/: React Native components and navigation.
  • Core SDKs provide foundational services (e.g., SecurityCore, StorageCore) that feature data layers depend on.
  • Apps initialize and compose SDKs; they own configuration and feature toggles.

• Entry points & configuration

  • apps/api-bff/src/main.ts: Fastify server + Apollo schema wiring and middleware registration.
  • apps/*/App.tsx: SDK initialization sequence (Security → Storage → Sync → Runtime → Trust) and navigation bootstrapping.
  • packages/*/src/index.ts: Barrel files re-exporting public API for each package.
  • tsconfig.base.json: Strict TypeScript with path aliases for all packages.

3. Test Strategy

• Framework: Jest (Nx managed). Use per-package unit tests with co-located *.spec.ts(x) files.
• Suggested organization (based on architecture):
  • Domain layer: Unit tests for use cases (pure, no I/O). Mock via interfaces.
  • Data layer: Contract tests for GraphQL and network using MSW; integration tests with core SDKs.
  • Core SDKs: Unit tests for deterministic logic; integration tests for cross-SDK interactions.
  • Apps: E2E tests with Detox for key flows.
• Mocking guidelines:
  • Mock via domain interfaces (e.g., IAuthRepository, ITrustRepository) rather than concrete classes.
  • For GraphQL, prefer MSW to mock network boundaries rather than stubbing internals.
  • Use dependency injection to pass fakes/mocks into use cases.
• Coverage expectations:
  • Aim high on domain logic (>90%).
  • Maintain pragmatic coverage for data/adapters; prefer integration and contract tests.
• CI:
  • Use nx affected:test for efficient runs.

4. Code Style

• Languages & typing
  • TypeScript with strict mode enabled. Prefer precise types and interfaces over any.
  • Public APIs should have explicit return types (ESLint warns on missing types).
  • Favor async/await over promise chains; avoid top-level side effects.
• Naming conventions
  • Classes: PascalCase (e.g., SecurityCore, LoginUseCase).
  • Functions/variables: camelCase.
  • Files: index.ts as package barrels; core classes often use PascalCase file names (e.g., SecurityCore.ts). Keep barrels aligned with actual exports.
  • Packages follow scopes (@core/, @feature-/domain|data|ui-rn, @shared/*).
• Formatting
  • Prettier: singleQuote, semi, printWidth 100, arrowParens avoid, LF line endings.
  • Enforced via lint-staged on staged files.
• Lint rules & boundaries
  • ESLint: no-unused-vars (ignore args prefixed with _), explicit-function-return-type warn.
  • Module boundaries via @nx/enforce-module-boundaries with tags:
    • type:domain → only depend on [type:domain, type:types, scope:shared].
    • type:data → depend on [type:domain, type:types, scope:core, scope:shared].
    • type:ui → depend on [type:data, type:domain, type:types, scope:shared].
    • scope:feature cannot depend on other scope:feature.
    • scope:core only depends on [scope:core, scope:shared, type:types].
    • platform:shared cannot depend on platform:rn or platform:node.
  • Ensure each Nx library is properly tagged to satisfy these constraints.
• Documentation & comments
  • Use concise JSDoc for public APIs and to mark FRD references (e.g., F.SC.004).
  • Map errors to user-friendly codes/messages at boundaries (see LoginUseCase.handleLoginError).
• Error handling
  • Guard methods with ensureInitialized() where applicable (e.g., SecurityCore, StorageCore).
  • On server, do not expose internals in production (see BFF formatError).

5. Common Patterns

• Clean Architecture layering (UI → Data → Domain → Shared Types) and dependency inversion via interfaces.
• SDK initialization order in apps: Security → Storage → Sync → Runtime → Trust → Feature SDKs.
• Barrel exports (index.ts) per package for a stable public surface.
• GraphQL BFF:
  • Fastify plugins for security (helmet, cors) and custom plugins (security, rateLimit).
  • Middleware order: DPoP → Auth → Policy (ABAC) before GraphQL handler.
  • Dynamic imports for optional dependencies (e.g., Permit.io client).
• Security & cryptography
  • Hardware-backed keys, DPoP proof generation, envelope encryption with organizational DEKs.
  • Cryptographic erasure and secure wipe via key management.
• Offline-first storage
  • Encrypted local DB, schema registry, selective purge by organization, re-keying (planned).

6. Do's and Don'ts

• Do
  • Initialize core SDKs in the documented order before feature initialization.
  • Keep domain logic pure and free from platform or network code.
  • Depend on interfaces in domain; implement in data with adapters to core SDKs/BFF.
  • Use path aliases from tsconfig.base.json; export public API via index.ts.
  • Respect ESLint module boundaries and Nx tags; add proper library tags when creating new packages.
  • Map server errors to safe messages in production; log full details server-side only.
  • Use MSW for network contract tests; keep unit tests fast and deterministic.
  • Follow Conventional Commits with configured scopes and the additional security type.
  • Keep barrel files accurate and synchronized with actual implementation files.
• Don't
  • Import across features (no feature-to-feature dependencies).
  • Make domain depend on data/core/platform code.
  • Bypass ensureInitialized guards in core SDKs.
  • Expose stack traces or sensitive details to clients in production.
  • Hardcode secrets or environment-specific values; use config and env vars.
  • Introduce Node-specific APIs into React Native code paths.

7. Tools & Dependencies

• Tooling

  • PNPM workspaces + Nx orchestration (caching, affected commands).
  • ESLint + Prettier + lint-staged; commitlint with conventional commits.
  • Changesets for versioning and publishing (SDK packages only).

• Key libraries

  • Apps: React Native, React Navigation.
  • BFF: Fastify, @apollo/server, @graphql-tools/schema, @fastify/cors, @fastify/helmet, optional Permit.io.
  • Core SDKs: Security (DPoP, key management, encryption), Storage (encrypted DB, schema registry), Sync/Runtime/Trust (per architecture).

• Setup

  • Install: pnpm install; build: pnpm nx run-many -t build.
  • Dev scripts: dev:playground, dev:pro, dev:foundation.
  • Tests: pnpm test or pnpm affected:test.
  • BFF env vars: NODE_ENV, PORT (default 4000), HOST (default 0.0.0.0), PERMIT_PDP_URL, PERMIT_API_KEY.

• Separation of concerns (Clean Architecture conventions)

  • Feature SDKs:
    • domain/: Pure business logic (use cases, entities, interfaces). No platform or infra dependencies.
    • data/: Repositories/adapters that implement domain interfaces and talk to core SDKs and BFF.
    • ui-rn/: React Native components and navigation.
  • Core SDKs provide foundational services (e.g., SecurityCore, StorageCore) that feature data layers depend on.
  • Apps initialize and compose SDKs; they own configuration and feature toggles.

• Entry points & configuration

  • apps/api-bff/src/main.ts: Fastify server + Apollo schema wiring and middleware registration.
  • apps/*/App.tsx: SDK initialization sequence (Security → Storage → Sync → Runtime → Trust) and navigation bootstrapping.
  • packages/*/src/index.ts: Barrel files re-exporting public API for each package.
  • tsconfig.base.json: Strict TypeScript with path aliases for all packages.

3. Test Strategy

• Framework: Jest (Nx managed). Use per-package unit tests with co-located *.spec.ts(x) files.
• Suggested organization (based on architecture):
  • Domain layer: Unit tests for use cases (pure, no I/O). Mock via interfaces.
  • Data layer: Contract tests for GraphQL and network using MSW; integration tests with core SDKs.
  • Core SDKs: Unit tests for deterministic logic; integration tests for cross-SDK interactions.
  • Apps: E2E tests with Detox for key flows.
• Mocking guidelines:
  • Mock via domain interfaces (e.g., IAuthRepository, ITrustRepository) rather than concrete classes.
  • For GraphQL, prefer MSW to mock network boundaries rather than stubbing internals.
  • Use dependency injection to pass fakes/mocks into use cases.
• Coverage expectations:
  • Aim high on domain logic (>90%).
  • Maintain pragmatic coverage for data/adapters; prefer integration and contract tests.
• CI:
  • Use nx affected:test for efficient runs.

4. Code Style

• Languages & typing
  • TypeScript with strict mode enabled. Prefer precise types and interfaces over any.
  • Public APIs should have explicit return types (ESLint warns on missing types).
  • Favor async/await over promise chains; avoid top-level side effects.
• Naming conventions
  • Classes: PascalCase (e.g., SecurityCore, LoginUseCase).
  • Functions/variables: camelCase.
  • Files: index.ts as package barrels; core classes often use PascalCase file names (e.g., SecurityCore.ts). Keep barrels aligned with actual exports.
  • Packages follow scopes (@core/, @feature-/domain|data|ui-rn, @shared/*).
• Formatting
  • Prettier: singleQuote, semi, printWidth 100, arrowParens avoid, LF line endings.
  • Enforced via lint-staged on staged files.
• Lint rules & boundaries
  • ESLint: no-unused-vars (ignore args prefixed with _), explicit-function-return-type warn.
  • Module boundaries via @nx/enforce-module-boundaries with tags:
    • type:domain → only depend on [type:domain, type:types, scope:shared].
    • type:data → depend on [type:domain, type:types, scope:core, scope:shared].
    • type:ui → depend on [type:data, type:domain, type:types, scope:shared].
    • scope:feature cannot depend on other scope:feature.
    • scope:core only depends on [scope:core, scope:shared, type:types].
    • platform:shared cannot depend on platform:rn or platform:node.
  • Ensure each Nx library is properly tagged to satisfy these constraints.
• Documentation & comments
  • Use concise JSDoc for public APIs and to mark FRD references (e.g., F.SC.004).
  • Map errors to user-friendly codes/messages at boundaries (see LoginUseCase.handleLoginError).
• Error handling
  • Guard methods with ensureInitialized() where applicable (e.g., SecurityCore, StorageCore).
  • On server, do not expose internals in production (see BFF formatError).

5. Common Patterns

• Clean Architecture layering (UI → Data → Domain → Shared Types) and dependency inversion via interfaces.
• SDK initialization order in apps: Security → Storage → Sync → Runtime → Trust → Feature SDKs.
• Barrel exports (index.ts) per package for a stable public surface.
• GraphQL BFF:
  • Fastify plugins for security (helmet, cors) and custom plugins (security, rateLimit).
  • Middleware order: DPoP → Auth → Policy (ABAC) before GraphQL handler.
  • Dynamic imports for optional dependencies (e.g., Permit.io client).
• Security & cryptography
  • Hardware-backed keys, DPoP proof generation, envelope encryption with organizational DEKs.
  • Cryptographic erasure and secure wipe via key management.
• Offline-first storage
  • Encrypted local DB, schema registry, selective purge by organization, re-keying (planned).

6. Do's and Don'ts

• Do
  • Initialize core SDKs in the documented order before feature initialization.
  • Keep domain logic pure and free from platform or network code.
  • Depend on interfaces in domain; implement in data with adapters to core SDKs/BFF.
  • Use path aliases from tsconfig.base.json; export public API via index.ts.
  • Respect ESLint module boundaries and Nx tags; add proper library tags when creating new packages.
  • Map server errors to safe messages in production; log full details server-side only.
  • Use MSW for network contract tests; keep unit tests fast and deterministic.
  • Follow Conventional Commits with configured scopes and the additional security type.
  • Keep barrel files accurate and synchronized with actual implementation files.
• Don't
  • Import across features (no feature-to-feature dependencies).
  • Make domain depend on data/core/platform code.
  • Bypass ensureInitialized guards in core SDKs.
  • Expose stack traces or sensitive details to clients in production.
  • Hardcode secrets or environment-specific values; use config and env vars.
  • Introduce Node-specific APIs into React Native code paths.

7. Tools & Dependencies

• Tooling
  • PNPM workspaces + Nx orchestration (caching, affected commands).
  • ESLint + Prettier + lint-staged; commitlint with conventional commits.
  • Changesets for versioning and publishing (SDK packages only).
• Key libraries
  • Apps: React Native, React Navigation.
  • BFF: Fastify, @apollo/server, @graphql-tools/schema, @fastify/cors, @fastify/helmet, optional Permit.io.
  • Core SDKs: Security (DPoP, key management, encryption), Storage (encrypted DB, schema registry), Sync/Runtime/Trust (per architecture).
• Setup
  • Install: pnpm install; build: pnpm nx run-many -t build.
  • Dev scripts: dev:playground, dev:pro, dev:foundation.
  • Tests: pnpm test or pnpm affected:test.
  • BFF env vars: NODE_ENV, PORT (default 4000), HOST (default 0.0.0.0), PERMIT_PDP_URL, PERMIT_API_KEY.