Merge pull request #2 from CenterForOpenScience/docs/arch-convetion

Documentation for Architecture, Project Structure and GIT

Author: AndriiSiuta

README.md

@@ -36,22 +36,6 @@ ng build
 
 This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed.
 
-## Running unit tests
-
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
-
-```bash
-ng test
-```
-
-## Running end-to-end tests
-
-For end-to-end (e2e) testing, run:
-
-```bash
-ng e2e
-```
-
 Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
 
 ## Additional Resources

docs/arch.md

@@ -0,0 +1,58 @@
+# 📂 Folder Structure
+
+Project based on principle **Feature-based Architecture**, this approach provides reusable and consistant
+features across the application.
+
+```bash
+📦 src/
+ ├── 📂 features/ # Каталог із функціональними модулями
+ │ ├── 📂 feature-name/
+ │ │ ├── 📂 feature.component.ts/html/scss # Component with template and styles, and base logic file
+ │ │ ├── 📂 feature-service.ts # Service or Facade to provide data for NGXS
+ │ │ ├── 📂 feature.store.ts # NGXS Store for feature
+ │ │ ├── 📂 feature.entitity.ts # Feature Interface for data, Types, Enums
+ │ │ ├── 📂 feature.guards.ts # Guard's for feature routing and permissions
+ │ │ ├── 📂 feature.resolvers.ts # Resolvers for data fetching and preloading
+ │ │ ├── 📂 feature.utils.ts # Additinal utils for feature (formBuilders, converters, mappers)
+ │ │ ├── feature.module.ts # Optional, if standalone
+ │ │ ├── feature.routing.ts # Export of standalone components by path
+ │
+ ├── 📂 core/ # Base module for global services, components, and state
+ │ ├── 📂 services/ # Global services (API, Auth, LocalStorage)
+ │ ├── 📂 components/ # Global components (Header, Footer, Sidebar)
+ │ ├── 📂 store/ # Core state management (Auth, Settings, Router)
+ │ ├── core.module.ts # Optional, but must have a provider for core.
+ │
+ ├── 📂 shared/ # Shared module for common components, directives, pipes, and services
+ │ ├── 📂 ui/ # Shared UI components (Button, Input, Modal), or wrappers for 3rd party
+ │ ├── 📂 directives/ # Shared Directives (ClickOutside, Draggable)
+ │ ├── 📂 pipes/ # Shared Pipes (Filter, Sort, Format)
+ │ ├── 📂 services/ # Services, Facades for shared logic (Http, LocalStorage)
+ │ ├── 📂 store/ # Shared State management (Settings, Theme, Language)
+ │
+ ├── app.routes.ts # General Entry point for routing
+ ├── main.ts # Providers Setup and Bootstrap
+ ├── package.json # Dependencies and Scripts
+
+
+---
+```
+
+## 🚀 Dynamic File Generation (Schematics)
+
+Use Angular CLI to generate new feature components, services, and modules.
+
+```sh
+ng generate component feature-name/components/new-component
+
+### 📌 Other Schematics:
+
+| **Entity** | **Command** |
+|--------------|----------------------------------------------|
+| 📌 **Service** | `ng g s feature-name/services/new-service` |
+| 📦 **Module** | `ng g m feature-name` |
+| 🔐 **Guard** | `ng g g feature-name/guards/auth-guard` |
+| 🔄 **Pipe** | `ng g p shared/pipes/currency-format` |
+| ✨ **Directive** | `ng g d shared/directives/highlight` |
+
+

docs/git-convention.md

@@ -0,0 +1,129 @@
+# 📌 Git Branch Naming Convention (Aligned with Angular Guideline)
+
+# 📖 Introduction
+
+### To maintain a clean commit history and improve team collaboration, we follow Angular Conventional Commits in our Git branch naming. This approach makes it easy to identify change types and automate release processes.
+
+# 🚀 Branch Naming Format
+
+### The branch name should follow the format:
+
+```bash
+<type>/<issue-id>-<short-description>
+
+type – type of change (inspired by Angular Commit Message Convention).
+
+issue-id – task or issue ID (optional but recommended).
+
+short-description – a brief description of the change.
+
+```
+
+# 📌 Available Types (type)
+
+### We use the following types to categorize changes:
+```bash
+| Type --- Purpose
+| feat --- Adding a new feature
+| fix --- Fixing a bug or issue
+| refactor --- Code refactoring without changing functionality
+| perf --- Performance improvements
+| test --- Adding or updating tests
+| chore --- Updating configurations, tools, or dependencies
+| docs --- Updating or adding documentation
+| style --- Code style changes (formatting, indentation, comments)
+| ci --- Changes in CI/CD pipeline
+| build --- Updates in build process or dependencies
+| revert --- Reverting previous changes
+```
+
+# 📝 Branch Naming Examples
+
+### Here are some examples of branch names:
+```bash
+* feat/1234-add-user-authentication
+* fix/5678-fix-login-bug
+* refactor/4321-optimize-api-calls
+* docs/7890-update-readme
+* test/8765-add-e2e-tests-for-dashboard
+
+```
+# 🛠 Example of Creating a Branch:
+
+### To create a new branch, use the following command:
+```bash
+git checkout -b feat/1234-add-user-authentication
+
+```
+
+# 🏆 Best Practices
+
+* ✅ Use short and clear descriptions in branch names. 
+* ✅ Follow a consistent style across all branches for better project structure.
+* ✅ Avoid redundant words, e.g., fix/1234-fix-bug (the word "fix" is redundant).
+* ✅ Use kebab-case (- instead of _ or CamelCase).
+* ✅ If there is no issue ID, omit it, e.g., docs/update-contributing-guide.
+
+# 🔗 Additional Resources
+
+**Conventional Commits**: https://www.conventionalcommits.org
+
+**Angular Commit Guidelines**: https://github.com/angular/angular/blob/main/CONTRIBUTING.md
+
+**Git Flow**: https://nvie.com/posts/a-successful-git-branching-model/
+
+# This branch naming strategy ensures better traceability and improves commit history readability. 🚀
+
+# 📝 Commit Message Formatting
+
+To ensure clear and structured commit messages, we follow the Conventional Commit format:
+
+🔹 **Commit Message Structure**
+
+```bash
+<type>(<scope>): <short description>
+
+[optional body]
+
+[optional footer]
+
+type – The type of change (e.g., feat, fix, docs, style, etc.).
+
+scope – A short context describing the part of the project affected (optional but recommended).
+
+short description – A concise summary of the change (in imperative form, e.g., "fix login bug").
+
+body – A more detailed explanation of the change (if necessary).
+
+footer – Additional metadata, e.g., references to issues (Closes #123).
+```
+
+# 📌 Example Commit Messages
+
+```bash
+
+feat(auth): add user authentication flow
+
+Implemented login, registration, and session handling.
+Closes #1234.
+
+fix(ui): resolve button alignment issue
+
+Fixed misalignment of buttons in the settings panel.
+
+docs(readme): update installation instructions
+
+Clarified step-by-step setup instructions for the project.
+
+```
+
+# 🔗 Additional Resources
+
+Conventional Commits: https://www.conventionalcommits.org
+
+Angular Commit Guidelines: https://github.com/angular/angular/blob/main/CONTRIBUTING.md
+
+Git Flow: https://nvie.com/posts/a-successful-git-branching-model/
+
+This branch naming and commit message strategy ensures better traceability and improves commit history readability. 🚀
+