{
  description = "Reference Board Viewer - Web-based visual reference management";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs =
    { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = nixpkgs.legacyPackages.${system};

        pythonEnv = pkgs.python3.withPackages (
          ps: with ps; [
            # Core backend dependencies
            fastapi
            uvicorn
            sqlalchemy
            alembic
            pydantic
            pydantic-settings # Settings management
            psycopg2 # PostgreSQL driver
            # Auth & Security
            python-jose
            passlib
            bcrypt # Password hashing backend for passlib
            email-validator # Email validation for pydantic
            # Image processing
            pillow
            # Storage
            boto3
            # HTTP & uploads
            httpx
            python-multipart
            # Testing
            pytest
            pytest-cov
            pytest-asyncio
          ]
        );
      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            # Python environment
            pythonEnv
            uv
            ruff

            # Database
            postgresql

            # Frontend
            nodejs
            nodePackages.npm

            # Image processing
            imagemagick

            # Storage
            minio
            minio-client

            # Development tools
            git
            direnv

            # Optional: monitoring/debugging
            # redis
          ];

          shellHook = ''
            echo "🚀 Reference Board Viewer Development Environment"
            echo ""
            echo "📦 Versions:"
            echo "   Python:     $(python --version)"
            echo "   Node.js:    $(node --version)"
            echo "   PostgreSQL: $(psql --version | head -n1)"
            echo "   MinIO:      $(minio --version | head -n1)"
            echo ""
            echo "📚 Quick Commands:"
            echo "   Backend:    cd backend && uvicorn app.main:app --reload"
            echo "   Frontend:   cd frontend && npm run dev"
            echo "   Database:   psql webref"
            echo "   Tests:      cd backend && pytest --cov"
            echo "   MinIO:      minio server ~/minio-data --console-address :9001"
            echo ""
            echo "📖 Documentation:"
            echo "   API Docs:   http://localhost:8000/docs"
            echo "   App:        http://localhost:5173"
            echo "   MinIO UI:   http://localhost:9001"
            echo ""

            # Set up environment variables
            export DATABASE_URL="postgresql://localhost/webref"
            export PYTHONPATH="$PWD/backend:$PYTHONPATH"
          '';
        };

        # Apps - Scripts that can be run with `nix run`
        apps = {
          default = {
            type = "app";
            program = "${pkgs.writeShellScript "help" ''
              echo "Available commands:"
              echo "  nix run .#lint      - Run linting checks"
              echo "  nix run .#lint-fix  - Auto-fix linting issues"
            ''}";
            meta = {
              description = "Show available commands";
            };
          };

          # Unified linting for all code
          lint = {
            type = "app";
            program = "${pkgs.writeShellScript "lint" ''
              set -e

              # Backend Python linting
              echo "🔍 Linting backend Python code..."
              if [ -d "backend" ]; then
                cd backend
                ${pkgs.ruff}/bin/ruff check --no-cache app/
                ${pkgs.ruff}/bin/ruff format --check app/
                cd ..
              else
                echo "⚠  Not in project root (backend/ not found)"
                exit 1
              fi

              # Frontend linting (if node_modules exists)
              if [ -d "frontend/node_modules" ]; then
                echo ""
                echo "🔍 Linting frontend TypeScript/Svelte code..."
                cd frontend
                npm run lint
                ${pkgs.nodePackages.prettier}/bin/prettier --check src/
                npm run check
                cd ..
              else
                echo "⚠  Frontend node_modules not found, run 'npm install' first"
              fi

              echo ""
              echo "✅ All linting checks passed!"
            ''}";
            meta = {
              description = "Run linting checks on backend and frontend code";
            };
          };

          # Auto-fix linting issues
          lint-fix = {
            type = "app";
            program = "${pkgs.writeShellScript "lint-fix" ''
              set -e

              echo "🔧 Auto-fixing backend Python code..."
              if [ -d "backend" ]; then
                cd backend
                ${pkgs.ruff}/bin/ruff check --fix --no-cache app/ || true
                ${pkgs.ruff}/bin/ruff format app/
                cd ..
              else
                echo "⚠  Not in project root (backend/ not found)"
                exit 1
              fi

              if [ -d "frontend/node_modules" ]; then
                echo ""
                echo "🔧 Auto-fixing frontend code..."
                cd frontend
                ${pkgs.nodePackages.prettier}/bin/prettier --write src/
                cd ..
              fi

              echo ""
              echo "✅ Auto-fix complete!"
            ''}";
            meta = {
              description = "Auto-fix linting issues in backend and frontend code";
            };
          };
        };

        # Package definitions (for production deployment)
        packages = rec {
          # Backend package
          backend = pkgs.python3Packages.buildPythonApplication {
            pname = "webref-backend";
            version = "1.0.0";
            pyproject = true;
            src = ./backend;

            build-system = with pkgs.python3Packages; [
              setuptools
            ];

            propagatedBuildInputs = with pkgs.python3Packages; [
              fastapi
              uvicorn
              sqlalchemy
              alembic
              pydantic
              pydantic-settings
              psycopg2
              python-jose
              passlib
              pillow
              boto3
              httpx
              python-multipart
              email-validator
              bcrypt
            ];

            meta = {
              description = "Reference Board Viewer - Backend API";
              homepage = "https://github.com/yourusername/webref";
              license = pkgs.lib.licenses.mit;
            };
          };

          # Frontend package (disabled until dependencies are installed)
          # To enable: run 'npm install' in frontend/, then uncomment this
          # frontend = pkgs.buildNpmPackage {
          #   pname = "webref-frontend";
          #   version = "1.0.0";
          #   src = ./frontend;
          #   npmDepsHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Update after first build
          #   buildPhase = ''
          #     npm run build
          #   '';
          #   installPhase = ''
          #     mkdir -p $out
          #     cp -r build/* $out/
          #   '';
          #   meta = {
          #     description = "Reference Board Viewer - Frontend SPA";
          #     homepage = "https://github.com/yourusername/webref";
          #     license = pkgs.lib.licenses.mit;
          #   };
          # };

          default = backend;
        };

        # NixOS VM tests
        checks = import ./nixos/tests.nix { inherit pkgs; };
      }
    );
}