Repair Dev Flow security and project proof

.env.example

@@ -0,0 +1,6 @@
+MONGODB_URL=mongodb://127.0.0.1:27017/dev-flow?replicaSet=rs0
+AUTH_SECRET=replace-with-a-random-secret
+AUTH_GITHUB_ID=replace-with-a-github-oauth-client-id
+AUTH_GITHUB_SECRET=replace-with-a-github-oauth-client-secret
+AUTH_GOOGLE_ID=replace-with-a-google-oauth-client-id
+AUTH_GOOGLE_SECRET=replace-with-a-google-oauth-client-secret

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      MONGODB_URL: mongodb://127.0.0.1:27017/dev-flow?replicaSet=rs0
+      AUTH_SECRET: ci-only-secret-not-used-outside-this-build
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Check types
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Audit production dependencies
+        run: npm audit --omit=dev --audit-level=high

.gitignore

@@ -31,6 +31,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel

README.md

@@ -1,36 +1,103 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Dev Flow
 
-## Getting Started
+Dev Flow is an in-progress full-stack developer Q&A project built with Next.js, TypeScript, Auth.js, MongoDB, and Mongoose. It explores the complete path from responsive React interfaces and validated forms to authenticated server actions, relational-style document references, and transactional question writes.
 
-First, run the development server:
+## Project status
+
+This is a portfolio and learning project, not a production service. Authentication, question discovery, question creation, and owner-checked editing are implemented. Question detail, answers, voting, collections, community, jobs, and profile experiences are still incomplete or represented by placeholder routes.
+
+No production users, traffic, performance results, or business outcomes are claimed.
+
+## Implemented scope
+
+The current application includes credentials sign-up and sign-in, GitHub and Google provider integration through Auth.js callbacks, responsive authentication and navigation interfaces, light and dark themes, a question list with search and filters, validated question forms, authenticated creation, owner-only editing, and tag assignment.
+
+Question and tag writes use a MongoDB transaction so the question, tag counters, and join documents are updated together. Search input is escaped before it becomes a regular expression, and exact tag matching treats user text as data rather than executable pattern syntax.
+
+Account and user persistence is internal to the authentication flow. The project does not expose generic public account or user CRUD endpoints. Password hashes are excluded from Mongoose queries by default and selected explicitly only during credentials verification.
+
+## Request and data flow
+
+```text
+React / Next.js interface
+        |
+        | validated form or authenticated action
+        v
+Next.js App Router + server actions
+        |
+        | session and ownership checks
+        v
+Mongoose models and transaction boundary
+        |
+        v
+MongoDB replica set or Atlas cluster
+```
+
+The browser renders the product interface and submits validated form data. Server actions establish the authenticated session and enforce ownership before a write. Mongoose models define users, accounts, questions, tags, answers, votes, collections, and interactions. MongoDB transactions require a replica set or a compatible managed cluster.
+
+## Technology
+
+- Next.js 16 App Router, React 19, and TypeScript
+- Tailwind CSS with Radix and shadcn-style interface primitives
+- React Hook Form and Zod validation
+- Auth.js with credentials, GitHub, and Google providers
+- MongoDB and Mongoose
+- Vitest, ESLint, and GitHub Actions
+
+## Local setup
+
+Dev Flow requires Node.js 20.9 or newer, npm, and a transaction-capable MongoDB deployment. A standalone local MongoDB process cannot run the transactional sign-up and question-write flows; use a local replica set or MongoDB Atlas.
 
 ```bash
+git clone https://github.com/ahmed-elsayed-programmer/dev-flow.git
+cd dev-flow
+npm ci
+cp .env.example .env.local
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Set the values in `.env.local` before testing authentication or database-backed routes:
+
+```dotenv
+MONGODB_URL=mongodb://127.0.0.1:27017/dev-flow?replicaSet=rs0
+AUTH_SECRET=replace-with-a-random-secret
+AUTH_GITHUB_ID=replace-with-a-github-oauth-client-id
+AUTH_GITHUB_SECRET=replace-with-a-github-oauth-client-secret
+AUTH_GOOGLE_ID=replace-with-a-google-oauth-client-id
+AUTH_GOOGLE_SECRET=replace-with-a-google-oauth-client-secret
+```
+
+Do not commit real credentials. The values in `.env.example` are placeholders.
+
+## Verification
+
+The repository uses the same commands locally and in GitHub Actions:
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm audit
+```
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+The automated tests currently cover regular-expression escaping, exact tag matching, password-selection defaults, required identity fields, and the tag-counter schema contract. They do not replace database-backed integration or browser tests.
 
-## Learn More
+## Known limitations
 
-To learn more about Next.js, take a look at the following resources:
+- Question detail, answers, votes, collections, community, jobs, and profiles are not complete.
+- OAuth behavior requires real provider credentials and has not been covered by automated integration tests.
+- Transactional sign-up and question writes require a MongoDB replica set or Atlas.
+- The project is not currently presented as deployed or production-ready.
+- End-to-end browser tests and database-backed integration tests remain future work.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Next improvements
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+The next implementation milestones are completing the question detail and answer flow, adding vote and collection behavior, covering authentication and question writes with database-backed tests, and validating the primary user journeys in a browser test suite.
 
-## Deploy on Vercel
+## Author
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+Ahmed Elsayed is a Full-Stack Engineer working with Python/Django and React/Next.js.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- [Portfolio](https://ahmedelsayed.vercel.app/)
+- [LinkedIn](https://www.linkedin.com/in/ahmed-elsayed-developer/)