249 lines
15 KiB
Markdown
249 lines
15 KiB
Markdown
# 📘 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.
|
|
|
|
|