Merge pull request #5 from authxt/docs

feat: add docs for project defence

Author: sijanthapa171

project-docs/design_rationale.md

@@ -0,0 +1,255 @@
+# Document Management System - Design Rationale
+
+## 1. Modular Architecture Benefits
+
+### 1.1 Separation of Concerns
+```
+src/
+├── main.c      # Core program flow
+├── cli.c       # Command-line handling
+├── file_ops.c  # File operations
+└── utils.c     # Utility functions
+```
+
+**Why This is Better:**
+1. **Maintainability**
+   - Each module has a single responsibility
+   - Easier to find and fix bugs
+   - Can modify one component without affecting others
+
+2. **Testability**
+   - Can test each module independently
+   - Easier to write unit tests
+   - Can mock dependencies for testing
+
+3. **Reusability**
+   - Utility functions can be reused across modules
+   - Can use components in other projects
+   - Reduces code duplication
+
+## 2. Data Structure Design
+
+### 2.1 Command Arguments Structure
+```c
+typedef struct {
+    command_type_t cmd_type;
+    char category[64];
+    char filename[256];
+    bool valid;
+} command_args_t;
+```
+
+**Benefits:**
+1. **Type Safety**
+   - Prevents command type errors
+   - Fixed buffer sizes prevent overflow
+   - Boolean validation flag for error checking
+
+2. **Clean Interface**
+   - All related data grouped together
+   - Easy to pass between functions
+   - Clear what data is needed for commands
+
+## 3. File System Organization
+
+```
+data/
+├── recipes/   # Category-based organization
+├── notes/
+├── logs/      # Operation history
+└── versions/  # Backup storage
+```
+
+**Advantages:**
+1. **Data Organization**
+   - Clear separation of different document types
+   - Easy to find and manage files
+   - Natural hierarchy for document management
+
+2. **Version Control**
+   - Separate versions directory keeps backups organized
+   - Original files remain in their categories
+   - Easy to track file history
+
+3. **Logging System**
+   - Centralized logs for all operations
+   - Easy to audit system usage
+   - Helps in troubleshooting
+
+## 4. Error Handling Strategy
+
+### 4.1 Comprehensive Error Checking
+```c
+if (!ensure_category_dir(category)) {
+    log_error("Failed to create directory");
+    return false;
+}
+```
+
+**Why This Approach:**
+1. **Reliability**
+   - Every operation is checked for failure
+   - Resources are properly cleaned up
+   - System stays in consistent state
+
+2. **Debugging**
+   - Clear error messages
+   - Operation logging helps trace issues
+   - Error state is properly propagated
+
+3. **User Experience**
+   - Immediate feedback on errors
+   - Clear what went wrong
+   - Suggests how to fix issues
+
+## 5. Memory Management
+
+### 5.1 Resource Handling
+```c
+char *filepath = malloc(512);
+if (!filepath) {
+    log_error("Memory allocation failed");
+    return NULL;
+}
+// ... use filepath ...
+free(filepath);
+```
+
+**Benefits:**
+1. **Memory Safety**
+   - All allocations are checked
+   - Resources are freed properly
+   - No memory leaks
+
+2. **Resource Cleanup**
+   - Systematic approach to resource management
+   - Files are properly closed
+   - Memory is properly freed
+
+## 6. Command Processing Pipeline
+
+### 6.1 Step-by-Step Processing
+```
+Input → Validation → Operation → Logging → Result
+```
+
+**Advantages:**
+1. **Predictable Flow**
+   - Clear sequence of operations
+   - Easy to understand and debug
+   - Consistent behavior
+
+2. **Validation First**
+   - Catches errors early
+   - Prevents invalid operations
+   - Saves system resources
+
+3. **Automatic Logging**
+   - Every operation is tracked
+   - Creates audit trail
+   - Helps in system monitoring
+
+## 7. Version Control Implementation
+
+### 7.1 Automatic Versioning
+```c
+// On update, before modifying file:
+snprintf(version_path, sizeof(version_path), 
+         "%s/%s_%s_%s", 
+         VERSIONS_DIR, category, timestamp, filename);
+```
+
+**Benefits:**
+1. **Data Safety**
+   - Never lose previous versions
+   - Can recover old content
+   - Tracks document evolution
+
+2. **Organization**
+   - Timestamp-based naming
+   - Category preservation
+   - Easy to find versions
+
+## 8. Configuration Management
+
+### 8.1 Centralized Constants
+```c
+#define MAX_INPUT_SIZE 4096
+#define DATA_DIR "data"
+#define VERSIONS_DIR "data/versions"
+```
+
+**Advantages:**
+1. **Maintainability**
+   - Easy to modify system limits
+   - Consistent values across codebase
+   - Single source of truth
+
+2. **Flexibility**
+   - Can change paths easily
+   - Can adjust size limits
+   - Easy to configure for different environments
+
+## 9. Build System Design
+
+### 9.1 Makefile Structure
+```makefile
+CC = gcc
+CFLAGS = -Wall -Wextra
+SOURCES = $(wildcard src/*.c)
+OBJECTS = $(SOURCES:.c=.o)
+```
+
+**Benefits:**
+1. **Automation**
+   - One command builds everything
+   - Handles dependencies automatically
+   - Only rebuilds what's necessary
+
+2. **Consistency**
+   - Same flags for all files
+   - Predictable build process
+   - Easy to modify build options
+
+## 10. Security Considerations
+
+### 10.1 Input Validation
+```c
+if (strstr(filename, "..") != NULL) {
+    log_error("Invalid filename: contains directory traversal");
+    return false;
+}
+```
+
+**Why This Matters:**
+1. **Security**
+   - Prevents directory traversal attacks
+   - Validates input data
+   - Maintains system integrity
+
+2. **Data Safety**
+   - Prevents accidental file overwrites
+   - Maintains data organization
+   - Protects system files
+
+## 11. Performance Optimizations
+
+### 11.1 Buffer Management
+```c
+#define BUFFER_SIZE 4096
+char buffer[BUFFER_SIZE];
+while ((bytes = fread(buffer, 1, BUFFER_SIZE, source)) > 0) {
+    fwrite(buffer, 1, bytes, dest);
+}
+```
+
+**Benefits:**
+1. **Efficiency**
+   - Optimal buffer sizes
+   - Minimizes system calls
+   - Efficient file operations
+
+2. **Resource Usage**
+   - Controlled memory usage
+   - Predictable performance
+   - Scales well with file size