chore: initialize repository with project rules, docs, and phase-1 ADRs

Set up the foundation for the adastra-portal project: - CLAUDE.md captures durable project rules (quality bar, security/perf/a11y as first-class, language, commit conventions, ADR proactivity). - docs/ and decisions/ scaffolding with maintained indexes (docs/README.md and decisions/README.md), MADR 4.0.0 template, and tag vocabulary. - Phase-1 ADRs (0001-0006) lock structural choices: ADR usage, Nx monorepo with the apps preset, naming convention (adastra-portal / portal-shell / portal-bff), Angular CSR/zoneless/Signals/Vitest, NestJS over Express, PostgreSQL with Prisma. - docs/setup/ guides translated to English. - .gitignore covers Node/Nx artifacts and the personal notes/ scratchpad. The Nx workspace itself is not yet bootstrapped; that step is gated on a revised setup guide aligned with the ADRs.
2026-04-29 20:43:00 +02:00
commit 79eee77594
15 changed files with 1170 additions and 0 deletions
@@ -0,0 +1,32 @@
+# Documentation index
+
+This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a `.md` file under `docs/` must be reflected here in the same change.
+
+## Conventions
+
+- Documentation is written in **English**.
+- One topic per file. Group related files into a folder when there are three or more.
+- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
+- For architectural decisions, do **not** add them here — they belong in [../decisions/](../decisions/) as MADR 4.0.0 ADRs.
+
+## Sections
+
+### Onboarding & environment
+
+Setup guides for new contributors:
+
+- [setup/01-wsl-terminal-setup.md](setup/01-wsl-terminal-setup.md) — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
+- [setup/02-dev-web-stack.md](setup/02-dev-web-stack.md) — Node via nvm, pnpm via corepack, Docker
+- [setup/03-angular-nx-monorepo.md](setup/03-angular-nx-monorepo.md) — Angular + Nx monorepo bootstrap
+
+### Architecture
+
+_Empty — to be populated as the project grows._
+
+### Operations & runbooks
+
+_Empty — to be populated when we deploy._
+
+### Security, performance, accessibility
+
+_Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs._
@@ -0,0 +1,134 @@
+# 🖥️ Modern WSL terminal (Zsh + Powerlevel10k)
+
+## Goal
+
+A terminal that is:
+
+* readable
+* fast
+* equipped with intelligent autocomplete
+* suited for modern development
+
+---
+
+## 1) Install Zsh
+
+```bash
+sudo apt update
+sudo apt install -y zsh
+```
+
+Set it as the default shell:
+
+```bash
+chsh -s $(which zsh)
+```
+
+Under WSL, add the following to `~/.bashrc`:
+
+```bash
+if command -v zsh >/dev/null 2>&1; then
+  exec zsh
+fi
+```
+
+---
+
+## 2) Install Oh My Zsh
+
+```bash
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
+```
+
+---
+
+## 3) Install Powerlevel10k
+
+```bash
+git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
+  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k
+```
+
+In `~/.zshrc`:
+
+```bash
+ZSH_THEME="powerlevel10k/powerlevel10k"
+```
+
+Then:
+
+```bash
+source ~/.zshrc
+p10k configure
+```
+
+---
+
+## 4) Install a Nerd Font (on Windows)
+
+Install a Nerd Font on Windows (MesloLGS NF recommended).
+
+Configure it in Windows Terminal:
+
+* Settings → Debian profile
+* Font → MesloLGS NF
+
+---
+
+## 5) Useful plugins
+
+```bash
+plugins=(
+  git
+  fzf
+  zsh-autosuggestions
+  zsh-syntax-highlighting
+)
+```
+
+Install them:
+
+```bash
+git clone https://github.com/zsh-users/zsh-autosuggestions \
+  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
+
+git clone https://github.com/zsh-users/zsh-syntax-highlighting \
+  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
+```
+
+---
+
+## 6) Modern CLI tools
+
+```bash
+sudo apt install -y \
+  bat eza fd-find ripgrep fzf zoxide
+```
+
+Recommended aliases:
+
+```bash
+alias ls="eza --icons"
+alias ll="eza -lh --git --icons"
+alias cat="batcat"
+alias grep="rg"
+alias find="fdfind"
+```
+
+---
+
+## 7) FZF
+
+Add to `~/.zshrc`:
+
+```bash
+[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
+```
+
+---
+
+## Result
+
+* A modern terminal
+* Fast navigation
+* Higher productivity
@@ -0,0 +1,100 @@
+# ⚙️ Web dev stack (Node + pnpm + tooling)
+
+## Goal
+
+Install a modern, reproducible stack.
+
+---
+
+## 1) Install Node via nvm
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+source ~/.zshrc
+```
+
+Install Node LTS:
+
+```bash
+nvm install --lts
+nvm alias default 'lts/*'
+```
+
+---
+
+## 2) Activate pnpm
+
+```bash
+corepack enable
+corepack prepare pnpm@latest --activate
+pnpm setup
+exec zsh
+```
+
+---
+
+## 3) Working tree
+
+Create a dev folder:
+
+```bash
+mkdir -p ~/dev
+cd ~/dev
+```
+
+⚠️ Do not work inside `/mnt/c` (slow I/O).
+
+---
+
+## 4) Conventions
+
+* ❌ No global Angular install
+* ✅ Use `pnpm dlx`
+* ✅ Versions pinned per project
+
+---
+
+## 5) Useful commands
+
+```bash
+pnpm install
+pnpm run dev
+pnpm run build
+pnpm run test
+```
+
+---
+
+## 6) VS Code
+
+Recommended extensions:
+
+* WSL
+* Angular Language Service
+* ESLint
+* Prettier
+* GitLens
+
+---
+
+## 7) Docker
+
+Install Docker Desktop (Windows).
+
+Enable:
+
+* Settings → WSL Integration → Debian
+
+Test:
+
+```bash
+docker ps
+```
+
+---
+
+## Result
+
+* Stable environment
+* Clean version management
+* Team-compatible
@@ -0,0 +1,116 @@
+# 🏗️ Angular monorepo with Nx + pnpm
+
+> ⚠️ This guide is **pending revision**: the placeholder workspace name (`my-workspace`) and app name (`web`) must be replaced with project-specific values, and the procedure must be extended to cover the Node API / BFF side. Treat the steps below as a baseline only.
+
+## Goal
+
+Create a scalable and maintainable architecture.
+
+---
+
+## 1) Workspace creation
+
+```bash
+cd ~/dev
+
+pnpm dlx create-nx-workspace@latest my-workspace \
+  --preset=angular-monorepo \
+  --pm=pnpm \
+  --appName=web \
+  --style=scss \
+  --routing=true \
+  --unitTestRunner=vitest
+```
+
+---
+
+## 2) Recommended layout
+
+```text
+apps/
+  web/
+
+libs/
+  shared/ui/
+  shared/data-access/
+  shared/util/
+  feature/auth/
+```
+
+---
+
+## 3) Generate libraries
+
+```bash
+pnpm nx g @nx/angular:library shared-ui
+pnpm nx g @nx/angular:library feature-auth
+```
+
+---
+
+## 4) Main commands
+
+```bash
+pnpm nx serve web
+pnpm nx build web
+pnpm nx test web
+pnpm nx lint web
+```
+
+---
+
+## 5) Workspace-wide commands
+
+```bash
+pnpm nx run-many -t lint test build
+pnpm nx affected -t lint test build
+```
+
+---
+
+## 6) Prettier
+
+`.prettierrc`:
+
+```json
+{
+  "singleQuote": true,
+  "semi": true,
+  "printWidth": 100
+}
+```
+
+---
+
+## 7) Git hooks
+
+```bash
+pnpm add -D husky lint-staged
+pnpm exec husky init
+```
+
+---
+
+## 8) CI/CD
+
+> ⚠️ The original procedure targeted GitLab CI. The project repository now lives on Gitea, so this section needs to be rewritten for Gitea Actions (or the chosen CI runner). Tracked under the next round of CI ADRs.
+
+---
+
+## 9) Daily workflow
+
+```bash
+pnpm install
+pnpm start
+pnpm nx g component login
+pnpm nx affected -t lint test build
+```
+
+---
+
+## Result
+
+* Scalable monorepo
+* Optimized builds
+* Fast CI
+* Clear architecture