How d4ndr4d3/toulmin works
Project Type and Purpose
• This is a full-stack, AI-powered social media application (“Toulmin Argumentation Platform”) built with React on the frontend and FastAPI on the backend.
• It ingests user posts (tweets/comments), performs real-time argument analysis (Toulmin model via GPT-4o), and visualizes argument structures. It also provides AI-driven writing assistance and discovery services (vector embeddings + semantic search).
File Structure
– Top-level directories:
• devcontainer & Dockerfile(s): IDE and container setup
• backend/: FastAPI application (routes, services, models, websockets)
• docker-compose.yml & nginx.conf: Docker orchestration and reverse proxy
• scripts/: helper scripts for deployment/testing
• tests/: automated tests
– Backend layering:
• app/routes: HTTP endpoints (authentication, tweets, comments, discovery, suggestions)
• app/services: business logic (embeddings, LLM calls, WebSocket coordination)
• database.py/models.py: MongoDB integration and Pydantic schemas
– Frontend structure:
• src/components: UI modules (TweetComposer, ToulminDiagram, WritingAssistant, AuthModal)
• public: static assets, index.html
– Configuration: environment files (.env, docker.env), Dockerfiles, CI workflows.
README for Additional Insights
– Tech stack: React 19 + TailwindCSS, FastAPI 3.11, MongoDB Atlas, Qdrant Cloud, OpenAI GPT-4o, JWT auth, WebSockets.
– Key flows:
• HTTP REST for CRUD + AI-powered suggestions
• Vector DB calls for semantic search
– Deployment options: standalone Docker, Docker Compose, cloud (Docker Hub image).
a. Main Components
1. Client Browser (React App)
2. NGINX Reverse Proxy (in front of backend)
3. FastAPI Backend
– Authentication Module (JWT)
– API Layer (routes: users, tweets, comments, discovery, suggestions)
– Services Layer
• LLM Service (OpenAI GPT-4o calls)
• Embeddings Service (Qdrant vector DB)
• WebSocket Manager (real-time updates)
– Data Layer (MongoDB)
4. External Services
– OpenAI API
– MongoDB Atlas
– Qdrant Cloud
b. Relationships & Interactions
• Browser → HTTP/HTTPS → NGINX → FastAPI routes
• FastAPI → MongoDB (CRUD on users, tweets, analysis results)
• FastAPI → Qdrant (store/query embeddings)
• FastAPI → OpenAI (Toulmin analysis, suggestions)
c. Architectural Patterns & Principles
• Layered Architecture (presentation, API, services, data)
• Single‐process monolith backend with modular services
• Containerization (Docker + docker-compose) for consistent environments
• API Gateway/Reverse Proxy (NGINX)
• Real-time messaging via WebSocket channel
d. Key Technologies
• Frontend: React 19, TailwindCSS, React Flow
• Backend: FastAPI, Python 3.11, Pydantic, WebSockets
• Databases: MongoDB Atlas (document store), Qdrant Cloud (vector store)
• AI: OpenAI GPT-4o
• DevOps: Docker, docker-compose, GitHub Actions, supervisord (devcontainer)