Docs/add project documentation

[esantoul]

Pull Request: Add Project Documentation and Development Setup

Description

Adds documentation and development setup to simplify onboarding and development. Includes:

• Documentation (4 guides)
• Dev Container setup for VS Code/Cursor
• Docker Compose configuration for local services
• Updated README with quick start

Type of Change

• Documentation
• New feature (Dev Container + Docker Compose)
• Bug fix
• Breaking change

Changes Summary

Documentation Added

1. ARCHITECTURE.md (537 lines)

   • Architecture overview
   • Monorepo structure
   • Package descriptions (@arrhes/api, @arrhes/platform, @arrhes/metadata, @arrhes/tools, @arrhes/website)
   • Tech stack
   • Data flows (auth, CRUD, file upload/download)
   • Authentication strategy
   • Database schema

2. CONFIGURATION.md (527 lines)

   • Environment variables for API and Tools
   • PostgreSQL setup (Docker Compose and native)
   • S3/MinIO configuration
   • SMTP/Email configuration
   • Security practices
   • Example configurations

3. DEVELOPMENT.md (954 lines)

   • Three development options (Dev Container, Docker Compose, Native)
   • Installation steps
   • Configuration
   • Database initialization
   • Development workflow
   • Scripts reference
   • Debugging
   • Troubleshooting

4. CONTRIBUTING.md (551 lines)

   • Code of conduct
   • Contribution guidelines
   • Code standards (TypeScript, React, naming)
   • Commit conventions
   • PR process
   • Testing guidelines

Development Infrastructure

1. Dev Container (.devcontainer/)

   • Dockerfile - Node.js 24.5+ with pnpm
   • devcontainer.json - VS Code/Cursor configuration
   • post-create.sh - Auto-setup script (installs deps, initializes DB, creates .env files)
   • README.md - Dev Container usage guide

2. Docker Compose (docker-compose.yml)

   • PostgreSQL service (port 5432)
   • MinIO service (ports 9000, 9001)
   • MailHog service (ports 1025, 8025)
   • Pre-configured with default credentials

3. Additional Files

   • .dockerignore - Docker build exclusions
   • Updated .gitignore - Dev container files
   • Updated README.md - Quick start guide with 3 options

Files Changed

13 files changed, 3279 insertions(+), 11 deletions(-)

Added:
- .devcontainer/Dockerfile
- .devcontainer/README.md
- .devcontainer/devcontainer.json
- .devcontainer/post-create.sh
- .dockerignore
- docs/ARCHITECTURE.md
- docs/CONFIGURATION.md
- docs/CONTRIBUTING.md
- docs/DEVELOPMENT.md

Modified:
- .gitignore
- README.md
- docker-compose.yml
- packages/platform/vite.config.ts

Pre-Merge Checklist

Build Methods Verification

Verify that all 3 build/setup methods work correctly:

1. Dev Container Method

   # In VS Code/Cursor:
   # 1. Open project
   # 2. Click "Reopen in Container"
   # 3. Wait for setup to complete
   # 4. Run: pnpm run build
   # 5. Verify all packages build successfully

2. Docker Compose Method

   # 1. pnpm install
   # 2. docker-compose up -d
   # 3. Configure .env files (see CONFIGURATION.md)
   # 4. pnpm --filter tools run push
   # 5. pnpm run build
   # 6. Verify all packages build successfully

3. Native Installation Method

   # 1. pnpm install
   # 2. Setup PostgreSQL locally
   # 3. Configure .env files (see CONFIGURATION.md)
   # 4. pnpm --filter tools run push
   # 5. pnpm run build
   # 6. Verify all packages build successfully

Documentation Review

Review all documentation files for accuracy:

• ARCHITECTURE.md

  • Architecture diagrams are accurate
  • Package descriptions match current codebase
  • Tech stack versions are correct
  • Data flow descriptions are accurate
  • Database schema matches actual models

• CONFIGURATION.md

  • All environment variables are documented
  • Docker Compose setup instructions work
  • Native setup instructions are clear
  • Example configurations are valid
  • Security recommendations are appropriate

• DEVELOPMENT.md

  • All 3 setup methods are clearly explained
  • Installation steps work as described
  • Scripts reference is complete and accurate
  • Troubleshooting section covers common issues
  • URLs and ports are correct

• CONTRIBUTING.md

  • Code standards match project conventions
  • Commit message format is clear
  • PR process is well-defined
  • Testing guidelines are appropriate

• README.md

  • Quick start instructions work
  • Links to documentation are correct
  • Feature list is accurate

Testing Instructions

Quick Verification

1. Build Test

   pnpm run build

   Should build all packages without errors.

2. Dev Container Test

   • Open in VS Code/Cursor
   • Reopen in Container
   • Verify auto-setup completes
   • Run pnpm run dev and verify app starts

3. Docker Compose Test

   docker-compose up -d
   docker-compose ps  # Verify all services are running

4. Documentation Links

   • Verify all internal links work
   • Check that code examples are valid
   • Ensure file paths are correct

Additional Notes

• All documentation is in French (as per project language)
• Dev Container setup includes automatic database seeding
• Docker Compose uses default credentials (documented for dev only)
• Documentation follows the existing project structure

Screenshots/Demo

N/A - Documentation and infrastructure changes

---

Ready for Review: Please verify the 3 build methods and review all documentation files before merging.