MindFlow is a Full Stack web application developed for the structured management of thoughts, publications, and ideas. Built with a focus on Clean Architecture and S.O.L.I.D. principles, the project ensures a clear separation of concerns. This facilitates scalability, code maintenance, and the rigorous implementation of automated tests.
The user interface is Server-Side Rendered (SSR) using the Express Handlebars template engine and styled with the Tailwind CSS, providing a fast, dynamic, and responsive user experience.
- 🔐 Authentication and Registration — Secure, session-based login system using
Argon2password hashing. - 💾 Persistent Sessions — Session management and storage in PostgreSQL via
connect-pg-simple. - 📝 Post Management (CRUD) — Creation, reading, updating, and deletion of publications on the user's dashboard.
- ⭐ Favorites System — Ability to save publications for quick access.
- 🔒 CSRF Protection — Built-in defense against Cross-Site Request Forgery.
- 🎨 Responsive Interface (UI) — Modern and adaptable layout, built and styled with Tailwind CSS v4.
- ✅ Form Validation — Rigorous data input validation and static typing using Zod.
- Use Cases (Interactors): All business logic flows are isolated into atomic and testable Use Cases within the Application layer.
- Adapter Pattern: Isolation of external libraries, such as data validation (Zod) and hashing algorithms (Argon2), ensuring that the business logic does not depend on third-party frameworks.
- Repository Pattern: Complete abstraction of database logic, facilitating provider switching and the creation of mocks (Harness) for testing.
- Factory Pattern: Clean and centralized dependency injection to instantiate Controllers, Use Cases, and Repositories.
| Technology | Purpose |
|---|---|
| Node.js | Runtime environment |
| Express 5 | Web framework |
| TypeScript | Static typing |
| Drizzle ORM | Database ORM |
| PostgreSQL | Relational database |
| Zod | Schema validation |
| Argon2 | Password hashing |
| Technology | Purpose |
|---|---|
| Handlebars | Server-side templating |
| Tailwind CSS v4 | Utility-first CSS |
| Technology | Purpose |
|---|---|
| Vitest | Unit and integration tests |
| Supertest | HTTP integration tests |
| Playwright | End-to-end tests |
| Technology | Purpose |
|---|---|
| Docker Compose | Local database containers |
| ESLint + Prettier | Linting and formatting |
| tsup | Build bundler |
| tsx | TypeScript execution in dev |
git clone https://github.com/Kaua26323/MindFlow.git
cd MindFlownpm installcp .env.example .env.developmentCheck the src/env/configs.ts file for more details on how we handle environments
npm run docker:devnpm run drizzle:migrate:dev# Start the server (with hot reload)
npm run dev
# In a separate terminal, compile CSS in watch mode
npm run dev:cssThe application will be available at http://localhost:3000 (or the port defined in your .env).
The project has three layers of testing:
npm run test:unit# Start the test database first
npm run docker:test
npm run drizzle:migrate:dev
npm run test:int# Run in headless mode
npm run test:e2e
# Run in headed mode (visible browser)
npm run test:e2e:headed
# Run with Playwright UI
npm run test:e2e:ui
# Debug mode
npm run test:e2e:debugnpm testThe project adopts Clean Architecture principles.
src/
├── application/ # APPLICATION LAYER (Pure Business Rules)
│ ├── ports/ # Abstraction contracts for external tools (e.g., hash.port.ts, validator.port.ts)
│ ├── repositories/ # Abstract persistence interfaces (e.g., user.repository.ts, post.repository.ts)
│ └── useCases/ # Implementation of system Use Cases, containing isolated application logic
│ ├── favorites/ # Favorites use cases (e.g., add-post.use-case.ts, remove-post.use-case.ts)
│ ├── posts/ # Posts use cases (e.g., create-post.use-case.ts, update-post.use-case.ts)
│ └── users/ # Users use cases (e.g., create-user.use-case.ts, user-login.use-case.ts)
│
├── infra/ # INFRASTRUCTURE LAYER (Technical Details and Frameworks)
│ ├── adapters/ # Concrete implementations of application Ports (e.g., argon2-hash.adapter.ts, zod-validator.adapter.ts)
│ ├── db/ # Data persistence subsystem
│ │ └── drizzle/ # Drizzle ORM configuration, relational schema definitions, and SQL migrations
│ │ ├── migrations/# Auto-generated SQL files for database version control
│ │ └── schemas/ # Relational table mapping (users, posts, favoritesPosts)
│ ├── repositories/ # Repository implementations using the database driver (drizzle-user.repository.ts)
│ ├── factories/ # Dependency injection factories coupling adapters and use cases to controllers
│ └── web/ # Specific payload validation schemas for HTTP requests via Zod
│
├── web/ # PRESENTATION LAYER (Web Interface and Routing)
│ ├── controllers/ # HTTP Controllers that receive view inputs, invoke use cases, and return responses
│ ├── middlewares/ # Express interceptors (authentication, global error handling, flash messages management)
│ ├── public/ # Directly served static files (Tailwind compiled CSS, favicons, manifests)
│ ├── routes/ # Express route definitions and grouping (user-routes.ts, post-routes.ts, etc.)
│ └── views/ # Visual layer using Server-Side Rendering (SSR) template engine
│ ├── dashboard/ # User logged-in area screens (post creation, listing, and editing)
│ ├── errors/ # Visual error handling pages (404, 500)
│ ├── favorites/ # Interface displaying user's favorited items
│ ├── layouts/ # System's base structural HTML5 template (main.handlebars)
│ └── partials/ # Reusable components (navigationBar.handlebars and modular SVG icons)
│
├── env/ # Fail-fast validation and static typing of environment variables using Zod schemas
└── errors/ # Abstractions and specializations of internal application errors (AppError)
This project is licensed under the MIT License.