π Appendices
Appendix¶
A. Glossary of Terms¶
Term | Definition |
---|---|
Modular Structure | Organizing folders by features or domains, where each contains its own logic, UI, tests, and services. Promotes isolation and encapsulation. |
Scalable Structure | Organizing folders by layers (api, services, models, infra, etc.) to support large teams, shared logic, and consistent abstraction boundaries. |
Hybrid Structure | A blend of modular (per feature) and scalable (per layer) architecture. Often starts modular and evolves into scalable. |
Feature Slice | A complete vertical set of files (UI, logic, tests) related to one business domain. |
Service Layer | A dedicated layer for reusable business logic, utilities, or model abstraction. Keeps features lightweight and testable. |
Separation of Concerns | Design principle that promotes separating code based on distinct responsibilities (UI, logic, data, etc.) |
High Cohesion | Keeping related pieces of logic close together to improve maintainability and understanding. |
Low Coupling | Reducing dependencies between components to ensure changes in one donβt break others. |
RAG | Retrieval-Augmented Generation. Combines vector search with GPT-style generation to create grounded, document-aware answers. |
B. Tools and Libraries Reference¶
Frontend¶
- React β Core frontend framework
- Vite β Lightning-fast dev server and bundler
- Tailwind CSS β Utility-first styling
- Zustand / Redux β State management
- React Query / SWR β Async data hooks
- Framer Motion β Animations
- React Router v6 β Routing
Backend¶
- FastAPI β Modern, async Python API framework
- Pydantic β Data validation via schemas
- Uvicorn β FastAPI ASGI server
- Tortoise ORM / SQLModel / SQLAlchemy β DB layers
- Celery β Background task manager
AI/NLP¶
- OpenAI (GPT) β Chat/completion APIs
- HuggingFace Transformers β Custom or local LLMs
- pgvector + Supabase β Vector storage and similarity search
- Tesseract / PaddleOCR β OCR engines
C. Recommended Folder Structures (Cheat Sheets)¶
Modular FastAPI (per-feature)¶
app/
βββ features/
βββ chat/
β βββ routes.py
β βββ services.py
β βββ schemas.py
Scalable FastAPI (per-layer)¶
app/
βββ api/
βββ services/
βββ schemas/
βββ core/
βββ vectorstore/
React Modular¶
src/
βββ features/
βββ chat/
β βββ ChatUI.tsx
β βββ chatSlice.ts
β βββ hooks.ts
β βββ chatService.ts
React Scalable¶
src/
βββ components/
βββ hooks/
βββ services/
βββ shared/
D. Formatter, Linter, and Dev Config Tips¶
Purpose | Tool | Config File |
---|---|---|
JavaScript Linting | ESLint |
.eslintrc.json |
Code Formatting | Prettier |
.prettierrc |
Python Linting | ruff |
pyproject.toml |
Python Formatting | black |
pyproject.toml |
Pre-commit Hooks | pre-commit |
.pre-commit-config.yaml |
π‘ Tip: Use Husky (JS) or
pre-commit
(Python) to enforce consistency before commits.
E. Further Reading and Resources¶
- Clean Architecture β Robert C. Martin
- Designing Software Architectures β Humberto Cervantes
- FastAPI Documentation β https://fastapi.tiangolo.com
- React App Structure Best Practices β Kent C. Dodds
- Microservices vs Monoliths β ThoughtWorks Tech Radar
- Supabase Docs β https://supabase.com/docs
- AI App Examples (LangChain, RAG) β https://github.com/hwchase17/langchain
F. Migration Checklist & Structure Audit Guide¶
Migration Checklist¶
- [ ] Identify duplicated logic (move to
services/
) - [ ] Audit cross-feature dependencies (refactor to shared)
- [ ] Move config/env to
core/
or.env
-based loaders - [ ] Restructure tests to mirror feature or layer
- [ ] Document folder responsibilities in a
README.md
Structure Audit Questions¶
- Are components tightly scoped to a domain?
- Is cross-feature logic reusable or duplicated?
- Can new developers find what they need in <5 seconds?
- Are routes, logic, and models clearly separated?
- Can you test a module in isolation?
- Are environments easy to switch between (dev, staging, prod)?
π Closing Words¶
A good folder structure is not set in stoneβbut it is intentional.
It evolves with your team, your product, and your ambition.
Structure isnβt just about where files live. Itβs about how people think, collaborate, and build things together.
So build for clarity.
Build for scale.
Build for the next developerβincluding future-you.
β Clay Mark Sarte