DevFlow

🚀 Project Status: Currently in active development. Core features are being implemented. Check back soon for the live demo!

✓ Node.js ≥ 22.13
✓ Yarn (via Corepack: `corepack enable`)
✓ MongoDB (local or Atlas)

# 1️⃣ Clone the repository
git clone https://github.com/osamaayub/DevFlow.git
cd DevFlow

# 2️⃣ Install dependencies (also applies patches/ via patch-package)
yarn install

# 3️⃣ Create a .env.local file in the project root
#    and add the variables listed below

# 4️⃣ At minimum set:
# MONGODB_URI, AUTH_SECRET (OAuth and OpenAI keys are optional)

# 5️⃣ Start development server
yarn dev

# 6️⃣ Open http://localhost:3000 in your browser 🎉

📝 Note: Env files are loaded per environment and are git-ignored for security.

# Development
yarn dev          # Start dev server (webpack)

# Production
yarn build        # Create optimized production build
yarn start        # Run production server

# Code Quality
yarn lint         # Run ESLint checks

• Project setup with Next.js 16 & TypeScript
• MongoDB & Mongoose integration with multiple models
• NextAuth.js authentication (Google, GitHub, Email/Password)
• Complete database models (Questions, Answers, Users, Tags, Accounts, Collections, Interactive, Votes, QuestionView, TagQuestion)
• Server actions for CRUD operations (questions, answers, tags, auth)
• Tailwind CSS & component styling with shadcn/ui
• Dark/Light theme support with context provider
• Rich text editor with MDX support
• Tag management system with tag-question relationships
• Search functionality with filtering
• Pagination system
• Error handling with custom error handler
• Validation schemas with Zod
• AI Answer API endpoint with OpenAI integration
• API client functions and centralized route constants
• Core UI pages (home, sign-in, sign-up, ask-question, question details, tags, collections)
• React components (forms, cards, navigation, editor, search, filters, shared utilities)
• User authentication flow (sign up, sign in, OAuth)
• Question creation and editing
• Save and remove questions with a stateful saved-star indicator
• Collection page listing the signed-in user's saved questions
• Answer creation
• Question view tracking
• Responsive design across implemented pages
• Local search bar with filtering
• Navigation sidebar and mobile navigation
• Theme toggle component
• User avatar components
• Relative time display
• Toast notifications with Sonner
• Form validation with React Hook Form
• Database connection management
• Structured logging with Pino
• API route handlers for users, accounts, auth, and AI
• OAuth callback handling and user account creation
• Password hashing with bcrypt
• Username generation for OAuth users
• Session management and JWT callbacks
• MongoDB transaction support for complex operations
• Tag processing and helper functions
• Question filtering (newest, unanswered, popular)
• URL utilities and helpers
• AI Answer UI integration (API implemented, UI Implemented)
• Vote system (upvotes/downvotes) for questions and answers with optimistic updates
• Home filters (newest, recommended, frequent, unanswered)
• Shared filter component for tags, collection, community, and answers
• Pagination for questions, tags, tag details, answers, collection, and community
• Tag details page
• Community page with search, filters, and member details page
• User profiles with editable profile details, activity tabs, statistics, and pagination
• Right sidebar with hot questions and popular tags
• Back button across pages
• MDX editor loaded client-side only (fixes "This page couldn't load" on ask-question and question details)
• CI workflow (lint, type-check, build) and Docker image publishing to GHCR

• Jobs page implementation (placeholder exists)
• Question deletion UI (deleteQuestion action exists)

• Interaction tracking - Schema exists, implementation pending
• Answer editing and deletion
• User management actions
• Live demo deployment
• Admin dashboard
• Real-time notifications
• Advanced analytics and reporting
• Community features (comments, discussions)
• Badge system and gamification
• API rate limiting
• Additional OAuth providers
• Enhanced search algorithms
• Performance optimizations
• Additional unit and integration tests

DevFlow/
├── src/
│   ├── app/                         # Routes only: thin pages, layouts, API handlers
│   │   ├── (auth)/                  # sign-in, sign-up
│   │   ├── (root)/                  # home, ask-question, questions/[id], tags, community, ...
│   │   ├── api/                     # REST endpoints (accounts, users, ai/answers, auth)
│   │   ├── layout.tsx
│   │   └── Providers.tsx
│   ├── features/                    # Vertical slices: one folder per domain
│   │   ├── answers/                 # actions.ts + components/ (AnswerForm, AnswerCard, AllAnswers)
│   │   ├── auth/                    # actions.ts, sign-out.action.ts + components/ (AuthForm, SocialAuthForm)
│   │   ├── collections/             # actions.ts (saved questions)
│   │   ├── community/               # actions.ts + components/ (UserCard, CommunityMemberProfile)
│   │   ├── questions/               # actions.ts + components/ (QuestionForm, QuestionCard, SaveQuestion)
│   │   ├── tags/                    # actions.ts, tag-helpers.ts + components/ (TagCards)
│   │   ├── users/                    # actions.ts + components/ (profile, activity, and profile editing)
│   │   └── votes/                    # actions.ts, vote-state.ts, components/, hooks/useVote.ts
│   ├── server/                      # Server-only infrastructure (never imported by client code)
│   │   ├── auth.ts                  # NextAuth configuration
│   │   ├── action.ts                # Validate + authorize + connect wrapper for server actions
│   │   ├── errors/                  # HTTP error classes, error handler
│   │   └── db/                      # connect.ts, models/, schemas/ (guarded by "server-only")
│   ├── shared/                      # Client-safe building blocks used across features
│   │   ├── api/                     # Typed fetch client for the REST endpoints
│   │   ├── components/              # ui/ (shadcn), common/, editor/, filters/, navigation/, search/
│   │   ├── constants/
│   │   ├── context/                 # Theme context
│   │   ├── lib/                     # utils, url, validation (zod), logger
│   │   └── types/
│   └── proxy.ts                     # Request proxy: forwards the question filter header
├── patches/                         # patch-package patches (next-themes)
├── public/                          # Static assets
├── .github/workflows/               # CI and deploy workflows
└── Dockerfile                       # Multi-stage standalone build

Dependency rules

• app → features → shared; server is used by app and feature actions.ts, never by client components.
• A feature is imported only through its public surface: @/features/<name>/components or @/features/<name>/actions. Features don't reach into each other's internals.
• Relative imports stay inside one area; anything crossing areas uses the @/ alias (@/* → src/*).

All responses follow the standard envelope format:

{ "success": true, "data": {...}, "statusCode": 200 }

Note: Questions, Answers, and Tags use Server Actions instead of REST API endpoints for better performance and type safety.

Questions, Answers, Tags, Votes, Collections, and Community are handled via Server Actions instead of REST API:

Build and run DevFlow in a containerized environment:

# Build the image
docker build -t devflow .

# Run the container
docker run -p 3000:3000 \
  -e MONGODB_URI="mongodb+srv://..." \
  -e AUTH_SECRET="your-secret-key" \
  -e AUTH_GITHUB_ID="your-github-id" \
  -e AUTH_GITHUB_SECRET="your-github-secret" \
  devflow

The image runs as a non-root user on port 3000 for security.

GitHub Actions automate testing and deployment:

1. Configure Settings → Environments in your GitHub repo
2. Add secrets for development and production environments:
   • MONGODB_URI
   • AUTH_SECRET
   • OAuth credentials
   • Docker registry credentials (if using GHCR)

• 🎯 Next.js App Router with Server Components and Server Actions
• 🧩 Client-only MDX editor loaded with next/dynamic to keep it out of server rendering
• 🗜️ Optimized Bundle with tree-shaking
• 📦 MongoDB Indexing for fast queries
• 🚀 Docker Multi-stage Build for minimal image size

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request against the dev branch

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Reference related issues in your PR

# Check your MONGODB_URI format
# Expected: mongodb+srv://username:[email protected]/dbname
# Make sure your IP is whitelisted in MongoDB Atlas

# Regenerate AUTH_SECRET
npx auth secret

# Verify OAuth credentials in your provider settings

# Clear cache and reinstall
rm -rf .next node_modules
yarn install
yarn build

This project is licensed under the MIT License — feel free to use it in your projects!

Have questions or want to contribute?

• 💬 GitHub Discussions — Ask questions & discuss features
• 🐛 Report Issues — Found a bug? Let us know
• 📖 Documentation — Coming soon with API guides & architecture
• 👥 Join Development — We welcome contributors!
• ⭐ Star the repo — Shows your support!