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

Add module-level index and boundary docs for the 28 top-level `src/` directories

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

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
38/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
documentation

Research direction

Start by listing the 12 index.ts barrels under src/ and reading .eslintrc.js around line 39 for the import/no-relative-parent-imports rule, since that sets the cross-directory import convention. The issue requires a maintainer-level decision on barrels before any edits, so raise that choice in the thread first. Done means the barrel convention is written down, the five largest directories (src/common/, src/core/, src/infrastructure/, src/investment/, src/blockchain/) each have a short README, docs/ARCHITECTURE.md links to them, and npx tsc --noEmit passes.

Written by the indexing model from the issue text.

Description

documentation intermediate refactor

Problem

src/ has 28 top-level directories and there are 12 index.ts barrel files scattered inside them, but no consistent barrel convention. The file count per directory varies from 0 (src/api/, src/models/ — pending removal) to 80 (src/common/).

There is no README in any src/ subdirectory. A contributor's first question — "which module owns this?" — is answered only by reading the directory name and guessing.

This overlaps with the docs/ARCHITECTURE.md issue; the difference is that this issue is about per-directory self-documentation at the point of use, not a single top-level document.

Suggested Direction

  1. Settle the barrel question first. 12 index.ts files exist today. Barrels are useful for cross-module imports and harmful for cycles and tree-shaking. Either standardise on them or remove them — but pick one. Note that import/no-relative-parent-imports is already error in .eslintrc.js:39, so cross-directory imports already have a convention.

  2. Add a short README.md to each major directory stating three things in a few lines:

    • what the module owns
    • what it depends on and what depends on it
    • where its tests live

    Start with the largest and most confusing: src/common/ (80 files), src/core/ (76), src/infrastructure/ (57), src/investment/ (46), src/blockchain/ (23).

  3. Have docs/ARCHITECTURE.md index them, so there is one entry point and the per-directory docs are the detail.

Constraints

  • Keep each per-directory README short — under 30 lines. These are orientation aids, not design documents.
  • Do not duplicate content that belongs in docs/. Link instead.
  • If you remove barrels, verify npx tsc --noEmit after each removal; they are load-bearing for module resolution in several places.

Acceptance Criteria

  • A barrel-file convention is documented, and the 12 existing index.ts files comply or are removed.
  • The five largest directories each have a README.md with owner, dependencies, and test location.
  • docs/ARCHITECTURE.md links to each directory README.
  • npx tsc --noEmit passes.
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.