Skip to content

Part 4: Hybrid and Advanced Techniques

17. Organizing Assets, Tests, and Configuration

“Folders aren't just for code.
They're for everything that keeps your project alive.”

Why This Chapter Matters

As your project matures, you’ll deal with more than just components and services. You’ll accumulate:

  • Images, videos, and static assets
  • Mock data and test fixtures
  • Environment configurations
  • Lint rules, formatters, and pre-commit tools
  • Docs for onboarding and architecture

If these aren't structured well, they rot.
If they’re structured intentionally, they accelerate development, testing, and collaboration.

This chapter walks you through how to organize the non-code side of your project at scale.

Organizing Assets: Images, Videos, Fonts, etc.

React Frontend (Vite)

frontend/
├── public/
│   ├── logo.svg
│   ├── blackhole.webm
│   └── manifest.json
├── src/
│   ├── assets/
│   │   ├── images/
│   │   ├── videos/
│   │   └── fonts/
Folder Purpose
public/ Static assets copied directly to /dist/
assets/ Imported assets via import img from './img.png'

Use assets/ for:

  • Project-scoped, importable files (e.g., logo, icons, sounds)
  • CSS-in-JS references
  • Fonts, background videos

FastAPI Backend

backend/
├── static/
│   ├── examples/
│   ├── uploads/
│   └── docs/

Mount like this:

app.mount("/static", StaticFiles(directory="static"), name="static")

Common backend assets:

  • Uploaded files (PDFs, images)
  • OCR outputs
  • Generated previews or processed artifacts

Organizing Tests and Fixtures

Folder Patterns

Frontend:

chatbot/
├── components/
│   └── ChatBox.tsx
├── __tests__/
│   └── ChatBox.test.tsx

Backend:

invoice/
├── services/
│   └── invoice_parser.py
├── __tests__/
│   └── test_invoice_parser.py

Shared:

shared/
├── test_helpers/
│   ├── mock_gpt.py
│   ├── fake_vectorstore.py
│   └── dummy_files/

Create dummy_files/ for test image uploads, mock PDFs, etc.

Feature-Based vs Centralized Testing

Style When to Use
Feature-based (__tests__/ in each module) Unit tests, close to logic
Centralized (tests/ at root) Integration/E2E, CI coverage reports
Hybrid (recommended) Use both—fast local tests, full-stack coverage

Organizing Environment Files and Secrets

Use per-app .env files, stored outside of Git.

Frontend:

.env.development
.env.production

Backend:

backend/
├── .env

Use .env.example in your repo for reference:

# backend/.env.example
OPENAI_API_KEY=your-key-here
DATABASE_URL=postgres://...

Tip: Use secret managers (GCP, Railway, GitHub) for CI environments.

Configuration: Linting, Formatting, Git Hooks

Store in root:

project-root/
├── .eslintrc.js / .pylintrc
├── .prettierrc / pyproject.toml
├── .editorconfig
├── .gitignore
├── .pre-commit-config.yaml

Use tools like:

  • ESLint + Prettier (React)
  • Black, Ruff, or Flake8 (FastAPI)
  • pre-commit for Git hook automation (format before commit)
  • Husky (Node) or pre-commit (Python) to enforce standards

Run pre-checks on every PR via CI.

Project Documentation

Create a docs/ folder at the root:

docs/
├── architecture.md
├── backend-schema.png
├── ai-pipeline.md
├── onboarding.md

You can also power:

  • A live developer portal (e.g., Docusaurus)
  • MkDocs (mkdocs.yml)
  • README embeds with diagrams

Tip: Store architectural diagrams (e.g., GPT + vector flow) alongside Markdown files using tools like Excalidraw or Diagrams.net.

Bonus: Folder Conventions for Miscellaneous Concerns

Folder Purpose
scripts/ One-off migration scripts, utility CLI scripts
jobs/ Scheduled background tasks or cronjobs
migrations/ Alembic or Prisma-style DB migrations
k8s/ or infra/ IaC configs for staging/prod
mock-data/ JSON/CSV test data for manual frontend mocking

Summary: Organizational Hygiene at Scale

Concern Best Practice
Static assets Use public/ and assets/ clearly
Feature tests Use __tests__/ per module
Integration tests Centralize under tests/ or e2e/
Mocks and test files Store in test_helpers/ or dummy_files/
Env vars Use .env, ignore real keys, commit .env.example
Docs Store architecture, onboarding, diagrams in docs/
Config Keep linters, formatters, pre-commit in project root

This isn’t “just organization.” It’s about reducing friction as your team and product grow.