Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Write `docs/ARCHITECTURE.md` — the module map and request lifecycle are undocumented

Open
  • Is something wrong?
#174 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
50/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
nodejs, typescript
Domain
backend, documentation

Research direction

Start with the global providers in src/app.module.ts (lines 306-321) and the architecture overview in README.md (lines 34-44), then list the directories under src/, including the empty src/api/ and src/models/. Resolve the src/portfolio/ versus src/investment/portfolio/ overlap and check which auth location is authoritative. Done when docs/ARCHITECTURE.md covers the five sections, uses Mermaid diagrams, and README.md links to it.

Written by the indexing model from the issue text.

Description

documentation help wanted intermediate

Problem

README.md describes the architecture in the abstract (lines 34-44, mapping responsibilities to NestJS concepts) but never shows the actual module tree. A newcomer reading it cannot answer basic questions: which of the 28 directories under src/ are active, what does each own, and what happens on a single request.

There are 12 files in docs/ (GRAPHQL_GATEWAY.md, RBAC.md, WEBSOCKET_SPECIFICATION.md, module-registry.md, monitoring.md, the portfolio set, stellar-reconciliation.md, MULTI_WALLET_MANAGEMENT.md, kubernetes-health-probes.md) but no architecture overview tying them together.

The confusion is not hypothetical — there are genuinely overlapping concepts. src/portfolio/ (3 files) and src/investment/portfolio/ (46 files) both exist. src/profiling/ and src/observability/ both contain profiling services. src/auth/ was removed in a past effort (issue #4, "Remove Orphaned Legacy Services in src/auth/") and src/core/auth/ took over. Contributors need a map that says which one is authoritative.

Why it matters

This is the highest-leverage documentation for new contributors, and it is the main reason good-first-issue contributors stall. Understanding request flow requires reading src/app.module.ts and chasing module imports across 545 files. Note CONTRIBUTING.md links to GitHub Discussions as the place to ask such questions — which means the questions are being asked, one at a time, forever.

Suggested Direction

Create docs/ARCHITECTURE.md and link it prominently from README.md.

Suggested contents:

  1. Module map — a table or tree of the src/ directories, what each owns, and its dependencies on other modules. This is the part that resolves the portfolio/ vs investment/portfolio/ ambiguity.
  2. Request lifecycle — what happens between an inbound request and a response: the four global providers registered in src/app.module.ts:306-321 (StrategyAuthGuard, DistributedRateLimitGuard, RolesGuard, KycGuard), then KycGuard/RolesGuard ordering, then the global ValidationPipe and GlobalExceptionFilter.
  3. Cross-cutting concerns — where auth, rate limiting, validation, observability and error handling live, and which are global versus module-scoped.
  4. Data layer — TypeORM entities and migrations, and the src/migrations/ conventions.
  5. Background work — Bull queues and scheduled jobs.
  6. Where to add a new feature — a short decision tree pointing at the right module.

Keep it factual and derived from the code. Cross-reference the existing docs/ files rather than duplicating them.

Constraints

  • Describe what the code does today, not what it should do. If you spot a structural problem, file a separate issue.
  • Every directory listed should exist; every existing directory should be listed. src/api/ and src/models/ currently contain 0 TypeScript files — say so explicitly or ask a maintainer whether they are placeholders to remove.
  • Diagrams should be Mermaid so they render in GitHub natively.

Acceptance Criteria

  • docs/ARCHITECTURE.md exists and covers all five sections above.
  • Every directory under src/ is accounted for, including the empty ones.
  • The request-lifecycle section names the four global guards from src/app.module.ts.
  • README.md links to it.
  • Diagrams are Mermaid and render correctly on GitHub.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.