CriticalThinking/PROJECT_STRUCTURE.md

# CriticalThinking Project Structure

## 1. Project Description
**CriticalThinking** is an autonomous agent system that performs deep architectural analysis of software projects. Inspired by `deep-thinking-agent` and `AI-Scientist`, it moves beyond simple linting to identify high-level design weaknesses, suggest structural improvements, and recommend state-of-the-art replacements (e.g., Hugging Face models) for custom implementations.

### In-app Integrations
- **Git-based Indexer**: Automatically clones and indexes codebases.
- **Deep-Thinking Orchestrator**: Uses iterative planning and reasoning (Planner -> Retriever -> Analyzer).
- **Hypothesis Generator**: Generates "Improvement Hypotheses" and validates them against the code context.
- **Hugging Face Hub**: Searches for replacement components.
- **Web Researcher**: Uses specialized MCP servers (harvesthealth/github-mcp-server) and Gradio clients to search GitHub and Hugging Face Spaces for community-driven solutions.

### Proposed FASTAPI Setup
- **App structure**:
  - `main.py`: App entry point.
  - `api/router.py`: API routes.
  - `services/`: Business logic and agent orchestration.
  - `tests/`: Automated tests.
- **Dependency injection**: Services are initialized per-task with appropriate configuration (LLM model, API keys).

## 2. Tasks and Tests
### Backend & Infrastructure
- **Task: Project Scaffolding**
  - *Test*: `tests/test_main.py` -> Verifies health check.
- **Task: Codebase Indexing Service**
  - *Test*: `tests/test_indexer.py` -> Verifies cloning, chunking, and search.

### Agent Logic
- **Task: Multi-Agent Orchestration**
  - *Test*: `tests/test_orchestrator.py` -> Verifies planning and analysis loop.
- **Task: Improvement & Replacement Logic**
  - *Test*: `tests/test_improvements.py` -> Verifies roadmap generation and HF matching.

### API & End-to-End
- **Task: API Exposure & Background Jobs**
  - *Test*: `tests/test_api.py` -> Verifies the full /analyze -> /report flow.

## 3. Functionality Expectations
### User Perspective
- Submit a repository URL.
- Receive a "Critical Thinking Report".
- View "Critical Weaknesses" and an "Improvement Roadmap".
- See "Suggested Replacements" (libraries/models) for custom code.

### Technical Perspective
- **Iterative Reasoning**: The agent doesn't just look at code once; it plans its investigation and refines its findings.
- **Schema-Aware RAG**: Uses structural context to find relevant code snippets.
- **External Knowledge**: Connects to Hugging Face Hub for modernization suggestions.

## 4. API Endpoints
- **POST /analyze**
  - Request: `{"repo_url": "string", "project_description": "string"}`
  - Response: `{"task_id": "uuid"}`
- **GET /report/{task_id}**
  - Response: `{"status": "completed", "report": {"weaknesses": [], "improvements": []}}`