CodeGuide-dev · CodeGuideDev · Aug 10, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/documentation/app_flowchart.md b/documentation/app_flowchart.md
@@ -0,0 +1,12 @@
+flowchart TD
+    Start[Start]
+    Start --> Input[User Input]
+    Input --> Outline[Automated Outline Generation]
+    Outline --> Analysis[Contextual Analysis and Summary Composition]
+    Analysis --> Decision{Need Template Customization}
+    Decision -->|Yes| Template[Customizable Template Framework]
+    Decision -->|No| Collaboration[Collaboration and Version Control]
+    Template --> Collaboration
+    Collaboration --> Export[Multi-Format Export and Integration]
+    Export --> UX[Intuitive User Experience]
+    UX --> End[Finish]
diff --git a/documentation/backend_structure_document.md b/documentation/backend_structure_document.md
@@ -0,0 +1,191 @@
+# Backend Structure Document
+
+This document outlines the design and setup of the backend system for our intelligent outline and summary generation tool. It covers architecture, databases, APIs, hosting, infrastructure, security, and maintenance. The goal is to give a clear, step-by-step view of how the backend works and how it’s hosted, without assuming deep technical knowledge.
+
+## 1. Backend Architecture
+
+Overview:
+- We use a service-oriented approach, breaking the backend into focused components (services) that handle specific tasks.
+- A central API Gateway routes requests from the frontend or other services to the right place.
+
+Key Components:
+- **API Gateway (Node.js + Express)**: Receives all incoming calls, handles authentication, and sends requests to the appropriate microservice.
+- **NLP Service (Python + Flask)**: Processes text inputs, runs natural language analysis, and returns summaries or outlines.
+- **Template Service (Node.js)**: Manages outline templates, applying user settings to generate custom outputs.
+- **Collaboration Service (Node.js)**: Tracks edits, comments, and versions for each project.
+- **Export Service (Node.js)**: Converts final documents into PDF, DOCX, or Markdown.
+- **Authentication Service**: Manages user accounts, tokens, and permissions.
+
+How It Supports:  
+- **Scalability**: Each service can be scaled independently. If the NLP processor needs more power, we add more instances without touching other services.  
+- **Maintainability**: Clear boundaries mean teams can work on one service without affecting others.  
+- **Performance**: Services communicate over fast internal networks; heavy tasks (like NLP) run in optimized environments.
+
+## 2. Database Management
+
+We use a combination of relational and non-relational databases to store different kinds of data:
+
+- **PostgreSQL (SQL)**
+  - User accounts, project metadata, version histories, and access controls.
+- **MongoDB (NoSQL)**
+  - Flexible storage of raw input texts, generated outlines, logs, and audit trails.
+- **Redis (In-Memory Cache)**
+  - Caches frequent lookups (user sessions, template data) to speed up responses.
+
+Data Practices:
+- Regular backups of PostgreSQL and MongoDB with automated snapshots.
+- Read-replicas for PostgreSQL to handle high read loads.
+- Data retention policies to archive or purge old logs.
+
+## 3. Database Schema
+
+### PostgreSQL Schema (Human-Readable)
+- **Users**: Stores user profiles and credentials.  
+  - ID, Email, PasswordHash, Name, CreatedAt
+- **Projects**: Holds information about each outline project.  
+  - ID, UserID, Title, Description, CreatedAt, UpdatedAt
+- **Templates**: Defines the structure and settings for outlines.  
+  - ID, UserID, Name, JSONDefinition, CreatedAt
+- **Versions**: Tracks changes to each project’s outline.  
+  - ID, ProjectID, TemplateID, VersionNumber, ChangeNotes, CreatedAt
+- **Comments**: Collaboration notes on specific sections.  
+  - ID, ProjectID, UserID, SectionReference, Text, CreatedAt
+
+### PostgreSQL Schema (SQL)
+```sql
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  name VARCHAR(100),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE projects (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id),
+  title VARCHAR(255) NOT NULL,
+  description TEXT,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE templates (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id),
+  name VARCHAR(100) NOT NULL,
+  json_definition JSONB NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE versions (
+  id SERIAL PRIMARY KEY,
+  project_id INTEGER REFERENCES projects(id),
+  template_id INTEGER REFERENCES templates(id),
+  version_number INTEGER NOT NULL,
+  change_notes TEXT,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE comments (
+  id SERIAL PRIMARY KEY,
+  project_id INTEGER REFERENCES projects(id),
+  user_id INTEGER REFERENCES users(id),
+  section_reference VARCHAR(255),
+  text TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### MongoDB Schema (NoSQL)
+- **Outlines Collection**:
+  - _id, projectId, rawInput, generatedOutline (array of sections), createdAt
+- **Logs Collection**:
+  - _id, serviceName, level, message, timestamp
+
+## 4. API Design and Endpoints
+
+We follow a RESTful style so that each endpoint represents a resource and uses standard HTTP methods.
+
+Key Endpoints:
+
+- **Authentication**  
+  - `POST /auth/register` – Create a new user account  
+  - `POST /auth/login` – Authenticate and return a token
+- **Projects**  
+  - `GET /projects` – List all projects for the user  
+  - `POST /projects` – Create a new project  
+  - `GET /projects/{id}` – Retrieve project details  
+  - `PUT /projects/{id}` – Update project metadata  
+  - `DELETE /projects/{id}` – Remove a project
+- **Outlines**  
+  - `POST /projects/{id}/outline` – Generate an outline from user input  
+  - `GET /projects/{id}/outline` – Fetch the latest outline
+- **Templates**  
+  - `GET /templates` – List user’s templates  
+  - `POST /templates` – Create a template  
+  - `PUT /templates/{id}` – Update a template
+- **Collaboration**  
+  - `GET /projects/{id}/comments` – List comments  
+  - `POST /projects/{id}/comments` – Add a comment
+- **Exports**  
+  - `POST /projects/{id}/export?format=pdf|docx|md` – Generate a downloadable file
+
+Authentication tokens are sent in the `Authorization` header as a Bearer token.
+
+## 5. Hosting Solutions
+
+We host in the cloud for reliability and easy scaling:
+- **Provider**: Amazon Web Services (AWS)
+- **Compute**: Containers managed by Elastic Container Service (ECS) or Elastic Kubernetes Service (EKS)
+- **Databases**:
+  - PostgreSQL on Amazon RDS with multi-AZ deployment  
+  - MongoDB Atlas for managed NoSQL hosting
+  - Redis on Amazon ElastiCache
+- **File Storage**: Amazon S3 for exported documents and backups
+- **Benefits**:
+  - High uptime with multi-zone failover
+  - Pay-as-you-go keeps costs aligned with usage
+  - Built-in monitoring and security tools
+
+## 6. Infrastructure Components
+
+- **Load Balancer**: AWS Application Load Balancer distributes incoming traffic across service instances.
+- **Caching**: Redis stores session data and template lookups for sub-millisecond response times.
+- **CDN**: Amazon CloudFront serves static assets (front-end bundle, exports) from edge locations.
+- **Containerization**: Docker images for each service, ensuring consistent environments.
+- **Orchestration**: ECS/EKS auto-scales containers based on CPU and memory usage.
+- **Service Discovery**: Internal DNS for services to find and communicate with each other securely.
+
+## 7. Security Measures
+
+- **Encryption**:
+  - TLS everywhere for in-transit data protection  
+  - AES-256 encryption at rest for databases and S3 buckets
+- **Authentication & Authorization**:
+  - JWT-based tokens with short lifetimes and refresh tokens  
+  - Role-based access control (RBAC) ensures users only see their own projects
+- **Network Security**:
+  - Private subnets for databases and internal services  
+  - Public subnets only for load balancers
+- **Data Validation**:
+  - Input sanitization to prevent injection attacks
+- **Compliance**:
+  - Regular security audits and vulnerability scanning
+
+## 8. Monitoring and Maintenance
+
+- **Monitoring Tools**:
+  - AWS CloudWatch for metrics and logs
+  - ELK (Elasticsearch, Logstash, Kibana) stack for centralized log analysis
+  - Prometheus + Grafana for service health dashboards
+- **Alerts**:
+  - Automated alerts on CPU/memory spikes, error rates, or high latency
+- **Backups & Updates**:
+  - Daily automated database snapshots, weekly full backups  
+  - Rolling updates to containers with zero downtime deployments  
+  - Dependency updates tracked by a CI/CD pipeline (GitHub Actions)
+
+## 9. Conclusion and Overall Backend Summary
+
+Our backend is a collection of specialized services working together through a simple API gateway. It uses reliable, managed databases and cloud infrastructure to ensure the system can grow as demand increases. Strong security and monitoring practices protect user data and guarantee high availability. These choices align with our goals of providing a fast, scalable, and dependable outline-generation tool that users can trust.
diff --git a/documentation/frontend_guidelines_document.md b/documentation/frontend_guidelines_document.md
@@ -0,0 +1,120 @@
+# Frontend Guideline Document
+
+This document outlines the frontend architecture, design principles, and technologies powering our Outline Generation and Summary Composition tool. It’s written in everyday language so everyone—technical or non-technical—can understand how the frontend is set up and why.
+
+## 1. Frontend Architecture
+
+### Overview
+We use a component-based setup built on React with TypeScript. Our build tool is Vite, chosen for fast startup and hot-module reloading.
+
+### Key Libraries and Frameworks
+- **React**: For building reusable UI components.
+- **TypeScript**: Adds type safety and better code clarity.
+- **Vite**: Modern build tool for quick development feedback.
+- **React Router**: Manages navigation between different pages.
+
+### Scalability, Maintainability, Performance
+- **Modular Components**: Each feature lives in its own folder, keeping code organized as the app grows.
+- **Lazy Loading**: We split code so that each section loads only when needed, speeding up initial page loads.
+- **Clear Type Definitions**: TypeScript interfaces describe data shapes, reducing bugs and making future changes easier.
+
+## 2. Design Principles
+
+We follow three main principles:
+
+### Usability
+- **Simple Flows**: Every screen guides users step by step—no surprises.
+- **Clear Labels**: Buttons and headings use everyday words (e.g., “Generate Outline,” “Download PDF”).
+
+### Accessibility
+- **Keyboard Navigation**: All interactive elements can be reached by tabbing.
+- **ARIA Labels**: Screen-reader friendly attributes on custom controls.
+- **Color Contrast**: Meets WCAG AA standards for text readability.
+
+### Responsiveness
+- **Mobile-First**: We design for phones first, then scale up to tablets and desktops.
+- **Flexible Layouts**: CSS Grid and Flexbox adapt to different screen sizes.
+
+## 3. Styling and Theming
+
+### Styling Approach
+- **Tailwind CSS**: Utility-first framework for quick and consistent styling.
+- **BEM Naming**: When writing custom CSS modules, we follow Block-Element-Modifier conventions.
+
+### Theming
+We keep a central theme file (`theme.ts`) defining colors, spacing, and typography. This ensures consistent branding.
+
+### Visual Style
+- **Style**: Modern flat design with subtle glassmorphism touches on modal backgrounds.
+- **Color Palette**:
+  - Primary: #4F46E5 (indigo)
+  - Secondary: #10B981 (emerald)
+  - Accent: #F59E0B (amber)
+  - Background: #F3F4F6 (light gray)
+  - Text: #111827 (dark gray)
+
+### Typography
+We use the **Inter** font (free from Google Fonts) for its clean, modern look. Headings are slightly heavier to create visual hierarchy.
+
+## 4. Component Structure
+
+We organize components by feature (also known as “feature folders”):
+
+- `src/components`: Shared UI elements like Button, Modal, Input.
+- `src/features/outline`: Components and hooks specific to outline generation (e.g., `OutlineForm`, `OutlinePreview`).
+- `src/features/summary`: Components for summary composition.
+
+### Reusability
+- **Atomic Design**: Atoms (Button, Input), Molecules (FormGroup), Organisms (OutlineForm).
+- **Single Responsibility**: Each component handles one piece of the UI, making maintenance straightforward.
+
+## 5. State Management
+
+We use React’s Context API with useReducer for global state:
+
+- **Context**: Stores user input, generated outline, and export options.
+- **Reducer**: Defines actions like `SET_INPUT`, `GENERATE_OUTLINE`, `RESET_DATA`.
+- **Local State**: Minor UI states (like modal open/closed) live in individual components via useState.
+
+This approach avoids over-complexity while keeping data flow clear.
+
+## 6. Routing and Navigation
+
+We use **React Router v6**:
+
+- `/`: Home page with tool description.
+- `/outline`: Outline generation interface.
+- `/summary`: Summary composition interface.
+- `/settings`: Theme and export preferences.
+
+Navigation is handled by a top-level `<Navbar>` component. Links update the URL without a full page reload.
+
+## 7. Performance Optimization
+
+### Strategies
+- **Code Splitting**: Each route’s code is loaded only when the user visits it.
+- **Lazy Loading Images**: Thumbnails and illustrations load as they scroll into view.
+- **Tree Shaking**: We rely on Vite’s optimized bundling to remove unused code.
+- **Minified Assets**: CSS and JS files are minified in production.
+
+These measures ensure fast load times and a snappy experience.
+
+## 8. Testing and Quality Assurance
+
+### Unit Tests
+- **Jest** + **React Testing Library** for testing components in isolation.
+- We aim for at least 80% coverage on core logic.
+
+### Integration Tests
+- Combine multiple components to test flows (e.g., entering input and seeing an outline preview).
+
+### End-to-End Tests
+- **Cypress**: Simulates user interactions—filling forms, clicking buttons, downloading files.
+
+### Linting and Formatting
+- **ESLint** + **Prettier** enforce code style.
+- **Husky** + **lint-staged** run checks before every commit.
+
+## 9. Conclusion and Overall Frontend Summary
+
+Our frontend is a modern, scalable React app that balances simplicity with performance. By following clear design principles, a component-based structure, and thorough testing strategies, we ensure a reliable and user-friendly experience. The consistent theming and responsive layouts keep the interface approachable on any device. This setup makes it easy to add new features—like alternative export formats or collaboration tools—without disrupting the core user experience.