conception-assistant/README.md

Design Journal

A collaborative design documentation tool with AI-powered assistance for technical project management.

Features

Document Management

• Rich text editor for design journals
• Automatic table of contents generation from headings
• Real-time Markdown preview with GitHub-style rendering
• Auto-save functionality with timestamp tracking
• Version history with undo/redo (Ctrl+Z/Y)

AI-Powered Assistant (Mistral AI)

• Rephrase: Improve clarity and style of selected text
• Analyze: Detect inconsistencies and duplicates in documents
• Advice: Get constructive improvement suggestions
• Enhanced Mode (Smart Adaptive): AI-driven iterative document enrichment
  • AI automatically selects which section to improve in each iteration
  • Smart section selection based on quality assessment, importance, and coverage
  • Up to 10 iterations of progressive enhancement
  • Real-time streaming feedback with section tracking
  • Precision control for creative vs. conservative improvements (30-90%)
  • Automatically avoids re-modifying recently enhanced sections

User Interface

• Dark/Light theme with preference persistence
• Split-panel layout with collapsible sidebars
• Responsive design for various screen sizes
• Keyboard shortcuts for common actions

Export & Import

• Export to Markdown (.md), PDF, or HTML
• Import existing Markdown files
• Default template for quick starts

Installation

Prerequisites

• Node.js 16+
• npm or yarn
• Mistral API key (optional, for AI features)

Setup

# Clone the repository
git clone <repository-url>
cd conception-assistant

# Install dependencies
npm install

# Create configuration file (optional)
cp .env.example config/.env
# Edit config/.env and add your Mistral API key

Configuration

Create a config/.env file with the following (all optional):

# Server Configuration
PORT=3000

# Mistral AI Configuration (required for AI features)
MISTRAL_API_KEY=your_mistral_api_key_here
MISTRAL_MODEL=mistral-large-latest
MISTRAL_BASE_URL=https://api.mistral.ai/v1

# AI Advanced Configuration
AI_ENABLED=true
AI_MAX_TOKENS=35000
AI_TEMPERATURE=0.3
AI_TOP_P=0.85

Note

: The application works perfectly for journal management without an API key. AI features will be disabled if no key is provided.

Running

# Start the application
npm start

# Access the application
# Open http://localhost:3000 in your browser

Usage

Creating a New Journal

1. Use the main editor to write your content
2. The table of contents updates automatically
3. Save with Ctrl+S or the Save button

Using AI Features

1. Rephrase: Select text → click "Rephrase" button
2. Analysis: Click "Inconsistencies", "Duplicates", or "Advice" buttons
3. Enhanced Mode (Smart Adaptive):
   • Choose number of iterations (1-10)
   • Select precision level (30-90%)
   • Click "Enhanced Mode"
   • AI automatically analyzes the entire document
   • At each iteration, AI selects ONE section to improve based on:
     • Quality assessment (incomplete sections, lacking details)
     • Strategic importance (introduction, architecture, APIs)
     • Coverage (avoids recently modified sections)
   • Watch real-time streaming with section badges showing which part is being enhanced
   • Document updates automatically after each iteration

Keyboard Shortcuts

• Ctrl+S - Save journal
• Ctrl+Z - Undo
• Ctrl+Y or Ctrl+Shift+Z - Redo
• Tab - Indent
• Esc - Close panels

Project Structure

conception-assistant/
├── app.js                   # Express server
├── package.json             # Dependencies and scripts
├── routes/                  # API routes
│   ├── index.js            # Main routes
│   ├── api.js              # Journal CRUD operations
│   ├── ai.js               # AI integration (Mistral)
│   ├── templates.js        # Template management
│   └── export.js           # PDF/HTML export
├── views/                   # HTML components
│   ├── page.js             # Main HTML structure
│   ├── header.js           # Header component
│   ├── main.js             # Main content area
│   └── footer.js           # Footer component
├── assets/                  # Static resources
│   ├── css/                # Stylesheets
│   └── js/                 # Client-side JavaScript
├── templates/              # Document templates
│   └── default.md          # Default template
└── data/                   # Journal storage
    └── journals_*.json     # Saved journals

AI Configuration

Temperature Settings by Feature

• Rephrase: 0.2 (very precise)
• Analysis: 0.1 (factual)
• Advice: 0.4 (balanced)
• Enhanced Mode: 0.1-0.9 (dynamic based on precision setting)

Enhanced Mode Precision Levels

Level	Description	Behavior	Use Case
30%	Very Creative	Can create 70% new logical content	Initial brainstorming
50%	Balanced	50/50 deduction/creation	Standard development
70%	Conservative	Primarily based on existing content	Document refinement
90%	Very Precise	Only obvious deductions	Technical finalization

Smart Adaptive Section Selection

The Enhanced Mode uses an intelligent strategy to automatically choose which section to improve:

Selection Criteria (in priority order):

1. Quality Assessment: Identifies sections that need improvement

   • Incomplete content (too short, missing details)
   • Vague or unclear explanations
   • Lack of technical specifications
   • Poor structure or organization

2. Strategic Importance: Prioritizes critical document sections

   • Introduction and overview sections
   • Architecture and design decisions
   • Core APIs and implementation details
   • Critical workflows and processes

3. Coverage Tracking: Ensures balanced enhancement

   • Avoids sections recently modified
   • Tracks modification history across iterations
   • Ensures all sections receive attention

4. Progressive Enhancement: Builds incrementally

   • Each iteration improves ONE section only
   • Maintains document coherence
   • Preserves all other sections unchanged

Output Format Per Iteration:

• Analyzed Sections: List of all major sections found in the document
• Selected Section: The specific section chosen for enhancement (with exact header name)
• Selection Reason: Explanation of why this section was prioritized
• Improvements Made: Detailed list of enhancements applied
• Next Recommendations: Suggestions for future iterations

Technology Stack

Backend

• Node.js - JavaScript runtime
• Express.js - Web framework
• Mistral AI - Language model API
• Puppeteer - PDF generation

Frontend

• Vanilla JavaScript - No framework dependencies
• Marked.js - Markdown parsing
• Mermaid.js - Diagram rendering
• CSS Variables - Dynamic theming

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Open Source

This project is open source and available under the MIT License. No attribution required.