docs: improve setup & contributing guide and add .env.example files#132
docs: improve setup & contributing guide and add .env.example files#132Sarthakkad05 wants to merge 20 commits intoAOSSIE-Org:mainfrom
Conversation
This document outlines the architecture and data flow of the Perspective application, detailing the client-server model, AI services, and data storage components.
This document outlines the Contributor Covenant Code of Conduct, detailing the community's pledge, standards, enforcement responsibilities, and consequences for violations.
📝 WalkthroughWalkthroughThis PR introduces comprehensive documentation and configuration guidance for the Perspective project. New files include ARCHITECTURE.md (with system design diagrams), CODE_OF_CONDUCT.md (contributor standards), CONTRIBUTING.md (setup and contribution workflow), and .example.env files for backend and frontend environments. README.md is restructured to serve as a condensed overview linking to detailed documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@backend/.example.env`:
- Around line 1-4: Add inline comments to the .env example explaining each
variable and how to obtain or generate the required values: annotate
GROQ_API_KEY with its purpose (Sanity/Groq API access) and where to get it,
PINECONE_API_KEY with Pinecone account/console steps, PORT with server binding
note and default, and SEARCH_KEY with Google Custom Search Engine / API key
acquisition and CSE ID if applicable; ensure each comment is concise, placed on
the same line as the variable, and uses consistent tone and formatting so new
contributors can quickly configure their environment.
- Around line 1-4: Add the missing OPENAI_API_KEY entry to the example env so it
matches CONTRIBUTING.md: insert a new variable line
OPENAI_API_KEY=<your_openai_api_key> into the .env example alongside
GROQ_API_KEY, PINECONE_API_KEY, PORT, and SEARCH_KEY; ensure the variable name
exactly matches OPENAI_API_KEY used in CONTRIBUTING.md and any runtime config so
contributors see consistent required keys.
In `@CONTRIBUTING.md`:
- Line 65: The copy command in CONTRIBUTING.md uses the wrong source filename;
change the shell command that currently references ".env.example" to use the
actual backend env filename ".example.env" so the step (cp .env.example .env)
succeeds—update the line in CONTRIBUTING.md accordingly.
In `@frontend/.env.example`:
- Line 1: Add inline comments to the .env.example by annotating each environment
variable with a short description; for example, document NEXT_PUBLIC_API_URL to
explain it is the frontend-accessible base URL for the backend API (used by
client-side fetches) and note expected formats (e.g., http://localhost:8000 or
https://api.example.com) and when to change it for production. Update the
NEXT_PUBLIC_API_URL entry in the file (and any other variables present) to
include these concise inline explanations next to the variable names.
In `@README.md`:
- Line 10: Update the broken link in README.md: replace the incorrect link
target "./CONTRIBUTING.md" with "./ARCHITECTURE.md" for the sentence that
references "ARCHITECTURE.md" so the displayed text and the href match; ensure
the markdown link text remains "ARCHITECTURE.md" and only the URL portion is
changed.
- Line 7: The Discord badge image tag in the README is missing alt text which
harms accessibility; update the <img> element (the Discord badge image) to
include a meaningful alt attribute (e.g., alt="Join our Discord community") so
screen readers can describe the image, ensuring the anchor and image structure
(<a href="https://discord.gg/hjUhu33uAn"><img ...></a>) remains unchanged aside
from adding the alt text.
🧹 Nitpick comments (2)
backend/.example.env (1)
1-4: Standardize placeholder format for consistency.The placeholder values use inconsistent formats:
<groq_api_key>,<your_pinecone_API_KEY>, and<your_Google_custom_search_engine_API_key>. Standardizing to a consistent pattern like<your_service_api_key>improves readability and professionalism.CONTRIBUTING.md (1)
68-75: Add brief explanations for each API key.To align with issue
#126's goal of reducing onboarding friction, consider adding a brief note explaining what each API key is used for and where to obtain it. This complements the inline comments that should be added to the .example.env file itself.📚 Example enhancement
4. Fill required keys: ```bash -OPENAI_API_KEY= -GROQ_API_KEY= -PINECONE_API_KEY= -SEARCH_KEY= +# Get these API keys from: +# - OpenAI/Groq: For LLM inference → console.groq.com or platform.openai.com +# - Pinecone: For vector database → app.pinecone.io +# - Google Custom Search: For fact-checking → console.cloud.google.com + +OPENAI_API_KEY=<your_key_here> +GROQ_API_KEY=<your_key_here> +PINECONE_API_KEY=<your_key_here> +SEARCH_KEY=<your_key_here> PORT=8000</details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
README.md
Outdated
|
|
||
| ## Setup & Deployment | ||
| 1. First, join the **[Discord Server](https://discord.gg/hjUhu33uAn) (Go to Projects->Perspective)** to chat with everyone. | ||
| 2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [ARCHITECTURE.md](./CONTRIBUTING.md) file. |
There was a problem hiding this comment.
Fix broken link to ARCHITECTURE.md.
The text says "ARCHITECTURE.md" but the link points to ./CONTRIBUTING.md. This will send users to the wrong document.
🔗 Proposed fix
-2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [ARCHITECTURE.md](./CONTRIBUTING.md) file.
+2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. For architecture details, see [ARCHITECTURE.md](./ARCHITECTURE.md).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [ARCHITECTURE.md](./CONTRIBUTING.md) file. | |
| 2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. For architecture details, see [ARCHITECTURE.md](./ARCHITECTURE.md). |
🤖 Prompt for AI Agents
In `@README.md` at line 10, Update the broken link in README.md: replace the
incorrect link target "./CONTRIBUTING.md" with "./ARCHITECTURE.md" for the
sentence that references "ARCHITECTURE.md" so the displayed text and the href
match; ensure the markdown link text remains "ARCHITECTURE.md" and only the URL
portion is changed.
Corrected link reference for CONTRIBUTING.md and added note about ARCHITECTURE.md.
Updated Discord server invite link with alt text for accessibility.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 1-127: Add a "Getting Started" (or "Quick Start") section to
README.md under the project description that lists prerequisites (Node.js,
Python, API keys), notes the new .example.env files included in this PR, and
provides concise setup steps: clone repo, copy .example.env -> .env, install
frontend deps with npm and backend deps with pip/poetry, then run the frontend
(Next.js) and backend (uvicorn/FastAPI) dev servers; end the section with a link
to CONTRIBUTING.md for full instructions. Reference the README's top-level
"Perspective" header and the existing CONTRIBUTING.md link so reviewers can
locate the change and verify the .example.env mention.
🧹 Nitpick comments (2)
README.md (2)
16-34: Consider consolidating redundant architecture information.The architecture component sections here (Frontend, Backend, AI & NLP, Data & Storage) overlap significantly with the Technical Stack table on lines 48-121. Both present the same technologies in different formats, creating maintenance overhead—any stack changes require updates in two places.
Consider keeping just one format:
- Option 1: Keep the descriptive sections (lines 16-34) for better context and remove the table
- Option 2: Keep the table (cleaner, scannable) and remove these sections
- Option 3: Move these detailed descriptions to ARCHITECTURE.md and keep only the table in README
37-37: Remove unnecessary HTML spacing entities.Line 37 contains
entities that appear to be leftover formatting artifacts. These don't serve a purpose in markdown and can be removed for cleaner source.
|
All review suggestions addressed. Ready for review. Thanks! |
1 participant
Fixes #126
This PR improves onboarding and documentation:
These changes make it easier for new contributors to understand the project structure and get started quickly.
Summary by CodeRabbit