@iservu-inc/adf-cli 0.1.6 → 0.2.0

package/.project/docs/architecture/SYSTEM-DESIGN.md

@@ -0,0 +1,369 @@
+# ADF CLI - System Architecture
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         CLI Entry                            │
+│                      (adf init)                              │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Session Manager                            │
+│         (Check for resumable sessions)                       │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+        ┌──────────────┴──────────────┐
+        │                             │
+        ▼                             ▼
+┌───────────────┐           ┌──────────────────┐
+│  Resume       │           │  New Session     │
+│  Existing     │           │  Workflow        │
+└───────┬───────┘           └────────┬─────────┘
+        │                            │
+        └─────────┬──────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Interviewer                             │
+│         (AI-driven conversational engine)                    │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+        ┌──────────────┼──────────────┐
+        │              │              │
+        ▼              ▼              ▼
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  Questions  │  │  Quality    │  │  Progress   │
+│  Database   │  │  Analyzer   │  │  Tracker    │
+└─────────────┘  └─────────────┘  └──────┬──────┘
+                                          │
+                        ┌─────────────────┼─────────────────┐
+                        │                 │                 │
+                        ▼                 ▼                 ▼
+                 ┌────────────┐    ┌───────────┐    ┌──────────────┐
+                 │ Main Save  │    │  Backup   │    │ Emergency    │
+                 │ JSON       │    │  JSON     │    │ Timestamped  │
+                 └────────────┘    └───────────┘    └──────────────┘
+                                          │
+                                          ▼
+                                 ┌─────────────────┐
+                                 │ Output          │
+                                 │ Generator       │
+                                 └────────┬────────┘
+                                          │
+                        ┌─────────────────┼─────────────────┐
+                        │                 │                 │
+                        ▼                 ▼                 ▼
+                 ┌────────────┐    ┌───────────┐    ┌──────────────┐
+                 │   PRP      │    │ Balanced  │    │    BMAD      │
+                 │  Output    │    │  Output   │    │   Output     │
+                 └────────────┘    └───────────┘    └──────────────┘
+```
+
+## Component Details
+
+### 1. CLI Entry (init.js)
+
+**Responsibilities:**
+- Parse command-line arguments
+- Check for existing sessions
+- Initialize workflow selection
+- Orchestrate interviewer
+
+**Key Functions:**
+- `init(options)`: Main entry point
+- Calls SessionManager to check for resume
+- Creates new Interviewer instance
+
+### 2. Session Manager (session-manager.js)
+
+**Responsibilities:**
+- List all sessions
+- Find resumable sessions
+- Prompt user to resume or start new
+- Delete sessions
+
+**Key Functions:**
+- `listSessions()`: Get all sessions
+- `getResumableSessions()`: Filter for in-progress
+- `promptToResume()`: Interactive prompt
+- `deleteSession(id)`: Remove session
+
+**Data:**
+- Reads from `.adf/sessions/{sessionId}/_progress.json`
+
+### 3. Interviewer (interviewer.js)
+
+**Responsibilities:**
+- Conduct conversational interview
+- Group questions into blocks
+- Show block previews
+- Ask questions with follow-ups
+- Track answers
+- Generate outputs
+
+**Key Functions:**
+- `start()`: Main interview loop
+- `askBlockQuestions()`: Ask all questions in block
+- `askQuestion()`: Ask single question with quality analysis
+- `determineFollowUp()`: Decide if follow-up needed
+- `generateOutputs()`: Create framework documents
+
+**State:**
+- `sessionId`: Unique session identifier
+- `answers`: All user answers
+- `transcript`: Full conversation log
+- `progressTracker`: Real-time progress
+
+### 4. Questions Database (questions.js)
+
+**Responsibilities:**
+- Store all framework questions
+- Provide questions by framework
+- Define question metadata
+
+**Structure:**
+```javascript
+{
+  id: 'prp-1',
+  phase: 'goal-definition',
+  text: 'Question text',
+  guidance: 'How to answer well',
+  goodExample: 'Example good answer',
+  badExample: 'Example bad answer',
+  keywords: ['web', 'mobile', ...],
+  requiredElements: ['platform', 'technology'],
+  followUpTriggers: {
+    vague: ['website', 'app'],
+    missingTech: (answer) => !hastech(answer),
+    missingPlatform: (answer) => !hasPlatform(answer)
+  }
+}
+```
+
+### 5. Answer Quality Analyzer (answer-quality-analyzer.js)
+
+**Responsibilities:**
+- Analyze answer richness
+- Calculate quality score (0-100)
+- Detect required elements
+- Determine if follow-ups needed
+
+**Scoring System:**
+```
+Word Count:          0-30 points
+Keywords:            0-20 points
+Required Elements:   0-25 points
+Detail Level:        0-15 points
+Technical Depth:     0-10 points
+─────────────────────────────────
+Total:               0-100 points
+```
+
+**Thresholds:**
+- Score >= 70: Comprehensive
+- Score >= 85: Skip follow-ups
+
+**Key Functions:**
+- `analyze(answer, question)`: Main analysis
+- `checkKeywords()`: Match expected terms
+- `checkRequiredElements()`: Detect critical info
+- `checkDetailLevel()`: Assess depth
+- `checkTechnicalDepth()`: Technical completeness
+
+### 6. Progress Tracker (progress-tracker.js)
+
+**Responsibilities:**
+- Track real-time progress
+- Calculate information richness
+- Save with triple redundancy
+- Enable resume capability
+
+**Progress Data:**
+```javascript
+{
+  sessionId: string,
+  framework: string,
+  status: 'in-progress' | 'completed',
+  startedAt: ISO timestamp,
+  lastUpdated: ISO timestamp,
+  completedAt: ISO timestamp | null,
+  totalBlocks: number,
+  currentBlock: number,
+  completedBlocks: array,
+  skippedBlocks: array,
+  totalQuestionsAnswered: number,
+  informationRichness: 0-100,
+  averageAnswerQuality: 0-100,
+  totalWordCount: number,
+  comprehensiveAnswers: number,
+  canResume: boolean,
+  answers: object,
+  transcript: array
+}
+```
+
+**Key Functions:**
+- `initialize()`: Load or create progress
+- `startBlock()`: Mark block as started
+- `completeBlock()`: Mark block as done
+- `skipBlock()`: Mark block as skipped
+- `answerQuestion()`: Save answer with quality
+- `saveWithBackup()`: Triple-redundant save
+- `complete()`: Mark session as done
+
+**Save Strategy:**
+1. Main: `_progress.json`
+2. Backup: `_progress.backup.json`
+3. Log: `_progress-log.md` (append-only)
+4. Emergency: `_emergency-{timestamp}.json` (if errors)
+
+### 7. Output Generator (output-generators.js)
+
+**Responsibilities:**
+- Transform Q&A into framework documents
+- Generate PRP, Balanced, or BMAD outputs
+- Create AI agent instructions
+
+**Outputs by Framework:**
+
+**PRP:**
+- `prp.md`: Product Requirement Prompt
+
+**Balanced:**
+- `constitution.md`: Project principles
+- `specification.md`: Detailed spec
+- `plan.md`: Technical plan
+- `tasks.md`: Task breakdown
+
+**BMAD:**
+- `prd.md`: Product Requirements Document
+- `architecture.md`: System architecture
+- `stories.md`: User stories
+
+## Data Flow
+
+### New Session Flow
+
+```
+1. User runs `adf init`
+2. SessionManager checks for resumable sessions
+3. User selects "New Session"
+4. Workflow detection or selection
+5. Interviewer creates session directory
+6. ProgressTracker initializes
+7. For each block:
+   a. Show block preview
+   b. User chooses answer/skip/quit
+   c. For each question in block:
+      i. Show question with guidance
+      ii. User provides answer
+      iii. Quality analyzer evaluates
+      iv. Progress tracker saves (triple-redundant)
+      v. Determine if follow-up needed
+      vi. If follow-up, ask and re-analyze
+   d. Complete block
+   e. Display progress
+8. Generate outputs
+9. Save transcript
+10. Mark session complete
+```
+
+### Resume Session Flow
+
+```
+1. User runs `adf init`
+2. SessionManager finds resumable sessions
+3. User selects session to resume
+4. Interviewer loads session data
+5. ProgressTracker loads from file
+6. Display resume info (last updated, progress)
+7. Continue from currentBlock
+8. [Same as steps 7-10 above]
+```
+
+## File Structure
+
+```
+project/
+├── .adf/
+│   └── sessions/
+│       └── {sessionId}/
+│           ├── _progress.json           # Main progress file
+│           ├── _progress.backup.json    # Backup
+│           ├── _progress-log.md         # Append-only log
+│           ├── _transcript.md           # Full conversation
+│           ├── _metadata.json           # Session metadata
+│           ├── qa-responses/
+│           │   ├── goal-definition.md
+│           │   ├── business-justification.md
+│           │   └── ...
+│           └── outputs/
+│               ├── prp.md               # (if PRP)
+│               ├── constitution.md      # (if Balanced)
+│               ├── specification.md     # (if Balanced)
+│               └── ...
+```
+
+## Error Handling
+
+### Save Failures
+
+```
+try {
+  await fs.writeJson(mainFile, data)
+  await fs.writeJson(backupFile, data)
+  await fs.appendFile(logFile, entry)
+} catch (error) {
+  // Emergency save
+  await fs.writeJson(emergencyFile, data)
+}
+```
+
+### Corrupted Progress File
+
+```
+if (await exists(mainFile)) {
+  try {
+    progress = await readJson(mainFile)
+  } catch {
+    // Try backup
+    progress = await readJson(backupFile)
+  }
+}
+```
+
+### Application Crash
+
+- On next run, SessionManager detects incomplete session
+- User prompted to resume
+- All data recovered from last successful save
+
+## Performance Considerations
+
+### Save Optimization
+
+- Asynchronous saves (non-blocking)
+- Debounce rapid saves (combine within 100ms)
+- Gzip compression for large transcripts
+
+### Memory Management
+
+- Stream large files instead of loading entirely
+- Clear transcript from memory after save
+- Lazy load question blocks
+
+## Security
+
+### Data Privacy
+
+- All data stored locally
+- No external API calls (except future analytics opt-in)
+- User owns all session data
+
+### Input Validation
+
+- Sanitize file paths
+- Validate JSON structure
+- Prevent path traversal attacks