Skip to content

filiplazov/MagicOrg

BranchesTags

Repository files navigation

MagicOrg - Full-Stack Management System

A modern, production-ready full-stack application for managing organizations and users, built with FastEndpoints (.NET 8) backend, React-admin frontend, MongoDB database, and Docker containerization.

✨ Features

Backend (FastEndpoints + .NET 8)

  • ✅ FastEndpoints 6.1.0 with Clean Architecture and Vertical Slice Architecture
  • ✅ MongoDB database with in-memory fallback for development
  • ✅ Docker & Docker Compose support for easy deployment
  • ✅ Enhanced seed data (40 organizations, 60 users)
  • ✅ Global API route prefix /api with versioning support
  • ✅ CORS enabled for frontend integration
  • ✅ Comprehensive error handling and validation

Frontend (React-admin + Vite)

  • ✅ React-admin with Material-UI components
  • ✅ Full CRUD operations for Users and Organizations
  • ✅ TypeScript support with proper type safety
  • ✅ Custom data provider for FastEndpoints API
  • ✅ Responsive design and mobile support
  • ✅ Search and filtering capabilities

Database & Infrastructure

  • ✅ MongoDB for production with Docker support
  • ✅ In-memory database for development and testing
  • ✅ Automatic database seeding with realistic data
  • ✅ Database migration support

Testing & Development

  • ✅ Playwright end-to-end tests
  • ✅ Unit tests for all business logic
  • ✅ Hot reload development setup
  • ✅ Production build optimization

🚀 Installation & Getting Started

Option 1: Docker (Recommended for Beginners)

This is the easiest way to get started - everything runs in Docker containers.

Prerequisites

  • Docker Desktop - Download here
    • Windows: Download Docker Desktop for Windows
    • Mac: Download Docker Desktop for Mac
    • Linux: Install Docker Engine and Docker Compose

Quick Start

# 1. Clone the repository
git clone <your-repo-url>
cd MagicOrg

# 2. Start everything with Docker Compose
docker-compose up

# 3. Open your browser and visit:
# - Application: http://localhost:5001
# - API Documentation: http://localhost:5001/swagger

That's it! Docker will automatically:

  • Build the frontend (React app)
  • Build the backend (.NET app)
  • Start MongoDB database
  • Seed the database with 40 organizations and 60 users
  • Connect everything together

Docker Commands

# Start services in background
docker-compose up -d

# View logs
docker-compose logs

# Stop services
docker-compose down

# Rebuild and restart (after code changes)
docker-compose down
docker-compose build
docker-compose up

# Reset database (removes all data)
docker-compose down -v
docker-compose up

Option 2: Local Development Setup

For developers who want to run everything locally without Docker.

Prerequisites

You need to install these tools on your machine:

1. .NET 8 SDK

  • Windows: Download from Microsoft .NET Download
  • Mac: brew install dotnet or download from Microsoft
  • Linux: Follow instructions for your distribution

2. Node.js (version 20+) and Yarn

  • Download Node.js from nodejs.org
  • Or use a version manager:
    • Mac: brew install node
    • Windows: Use the installer or winget install OpenJS.NodeJS
  • Install Yarn:
    • Mac: brew install yarn or npm install -g yarn
    • Windows: npm install -g yarn or use the installer from yarnpkg.com

3. MongoDB (Optional - uses in-memory by default)

  • Download from mongodb.com
  • Or use Docker: docker run -d -p 27017:27017 --name mongodb mongo:7.0

Installation Steps

# 1. Clone the repository
git clone <your-repo-url>
cd MagicOrg

# 2. Install backend dependencies
cd backend
dotnet restore

# 3. Install frontend dependencies  
cd ../frontend
yarn install

# 4. Return to project root
cd ..

# 5. Start the development servers
yarn dev

This will start:

Local Development Commands

# Start both frontend and backend
yarn dev

# Start only backend (API + Swagger)
yarn dev:backend

# Start only frontend
yarn dev:frontend

# Build for production
yarn build

# Run all tests
yarn test

# Run end-to-end tests
yarn test:e2e

🗄️ Database Configuration

The application supports two database modes:

In-Memory Database (Default)

  • Perfect for development and testing
  • No setup required
  • Data is reset when application restarts
  • Contains enhanced seed data (40 organizations, 60 users)

MongoDB Database

To use MongoDB instead of in-memory:

With Docker (easiest):

# Uses MongoDB automatically
docker-compose up

Local MongoDB:

# 1. Start MongoDB
docker run -d -p 27017:27017 --name mongodb mongo:7.0

# 2. Set environment variable
export Database__Provider=MongoDB

# 3. Start the application
yarn dev:backend

Configuration Options:

# Environment variables
export Database__Provider=MongoDB
export Database__MongoDB__ConnectionString=mongodb://localhost:27017/MagicOrg
export Database__MongoDB__DatabaseName=MagicOrg

📁 Project Structure

MagicOrg/
├── backend/                    # .NET 8 FastEndpoints API
│   ├── Features/              # Vertical Slice Architecture
│   │   ├── Organizations/     # Organization CRUD endpoints
│   │   │   ├── Create/       # Create organization feature
│   │   │   ├── Update/       # Update organization feature
│   │   │   ├── Delete/       # Delete organization feature
│   │   │   ├── GetById/      # Get single organization
│   │   │   └── List/         # List all organizations
│   │   └── Users/            # User CRUD endpoints (same structure)
│   ├── Domain/               # Domain entities (Organization, User)
│   ├── Infrastructure/       # Database implementations
│   │   └── Persistence/      # Database interfaces and implementations
│   ├── Tests/                # Shared test utilities
│   ├── Program.cs            # Application entry point
│   └── appsettings.json      # Configuration
├── frontend/                  # React-admin SPA
│   ├── src/
│   │   ├── resources/        # React-admin resource components
│   │   ├── providers/        # Custom data provider for API
│   │   ├── types/            # TypeScript type definitions
│   │   └── config/           # Configuration
│   ├── package.json          # Frontend dependencies
│   └── vite.config.ts        # Vite build configuration
├── tests/e2e/                # Playwright end-to-end tests
├── docker-compose.yml        # Docker configuration
├── docker-compose.dev.yml    # Alternative development configuration
├── Dockerfile                # Multi-stage Docker build
├── .env.example              # Environment variables template
└── package.json              # Root package.json for npm scripts

🔗 Available URLs

Docker Setup (Port 5001)

Local Development

MongoDB (if using Docker)

  • MongoDB: localhost:27017
  • Connection String: mongodb://admin:password123@localhost:27017/MagicOrg?authSource=admin

🧪 Testing

The project includes comprehensive testing at all levels:

# Run all tests (backend + frontend + e2e)
yarn test

# Backend unit tests only
yarn test:backend

# Frontend tests only
yarn test:frontend

# End-to-end tests (requires running application)
yarn test:e2e

# Run tests in Docker
docker-compose exec app yarn test

Test Structure

  • Backend: xUnit tests for all endpoints, services, and validators
  • Frontend: Component tests with testing-library
  • E2E: Playwright tests covering full user workflows

🏗️ Deployment

Docker Production Deployment

# 1. Build production images
docker-compose build

# 2. Start in production mode
docker-compose up -d

# 3. View application logs
docker-compose logs app

# 4. View database logs  
docker-compose logs mongodb

Traditional Deployment

# 1. Build frontend
cd frontend
yarn build

# 2. Build backend
cd ../backend
dotnet publish -c Release -o publish

# 3. Deploy 'publish' folder to your server
# The backend serves both API and frontend files

📊 API Reference

OpenAPI Specification

The API documentation is automatically generated and always up-to-date:

The OpenAPI specification is auto-generated from the FastEndpoints backend, ensuring it's always accurate and synchronized with the implementation. No manual maintenance required!

Organizations

  • GET /api/organizations - List all organizations with filtering
  • POST /api/organizations - Create new organization
  • GET /api/organizations/{id} - Get organization by ID
  • PUT /api/organizations/{id} - Update organization
  • DELETE /api/organizations/{id} - Delete organization

Users

  • GET /api/users - List all users with filtering
  • POST /api/users - Create new user
  • GET /api/users/{id} - Get user by ID
  • PUT /api/users/{id} - Update user
  • DELETE /api/users/{id} - Delete user

Query Parameters

# Pagination
GET /api/organizations?_start=0&_end=10

# Sorting
GET /api/organizations?_sort=name&_order=asc

# Filtering
GET /api/organizations?name=tech&description=software
GET /api/users?organizationId=123e4567-e89b-12d3-a456-426614174000

🔧 Configuration

Environment Variables

# Database Configuration
Database__Provider=InMemory          # or "MongoDB"
Database__MongoDB__ConnectionString=mongodb://localhost:27017/MagicOrg
Database__MongoDB__DatabaseName=MagicOrg

# Application Settings
ASPNETCORE_ENVIRONMENT=Development   # or "Production"
ASPNETCORE_URLS=http://+:5000

Configuration Files

  • backend/appsettings.json - Production settings
  • backend/appsettings.Development.json - Development overrides
  • .env.example - Environment variables template

🚨 Troubleshooting

Common Issues

Port already in use:

# Kill process using port 5000
lsof -ti:5000 | xargs kill -9

# Or use different port
docker-compose up --port 5001:5000

Docker issues:

# Reset Docker environment
docker-compose down -v
docker system prune -f
docker-compose up --build

Node.js version issues:

# Check version (need 20+)
node --version

# Update Node.js
# Mac: brew upgrade node
# Windows: Download latest from nodejs.org

MongoDB connection issues:

# Check MongoDB is running
docker ps | grep mongo

# Check connection
mongosh mongodb://localhost:27017/MagicOrg

Build errors:

# Clean and rebuild everything
rm -rf node_modules frontend/node_modules backend/bin backend/obj
yarn install
cd frontend && yarn install && cd ..
yarn build

Getting Help

  1. Check the logs:

    # Docker logs
docker-compose logs app

# Local development
yarn dev  # Watch console output

  2. Verify prerequisites:

    # Check versions
dotnet --version  # Should be 8.0+
node --version    # Should be 20+
docker --version  # Any recent version

  3. Test API manually:

    # Test backend is running
curl http://localhost:5000/api/organizations

# Or visit Swagger UI
open http://localhost:5000/swagger

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes
  4. Run tests: npm test
  5. Commit changes: git commit -m 'Add amazing feature'
  6. Push to branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📜 License

This project is licensed under the MIT License. See LICENSE file for details.

💡 Tips for New Developers

Start with Docker: If you're new to web development, use the Docker setup first. It handles all the complexity for you.

Learn the stack:

  • FastEndpoints: Modern alternative to ASP.NET Core MVC
  • React-admin: Admin interface framework for React
  • MongoDB: NoSQL document database
  • Docker: Containerization platform

Useful VSCode Extensions:

  • C# Dev Kit (for backend development)
  • ES7+ React/Redux/React-Native snippets
  • Prettier (code formatting)
  • Docker (container management)

Next steps:

  1. Try making small changes to see how everything connects
  2. Add a new field to organizations or users
  3. Create a new endpoint
  4. Customize the frontend interface
  5. Deploy to a cloud provider like Azure, AWS, or Digital Ocean

About

PoC

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages