Foundations

The three pillars of every software system

The Three Pillars

Every software system you will ever build — TradeCraft, the rental platform, a simple contact form — is made of three things:

That's it. Everything else is implementation details.

Databases: The Source of Truth

A database is where your application's state lives. State is just a fancy word for "what's true right now."

• Who are the users? → users table
• What trailers are available? → listings table
• What was AAPL's price at 2:35pm on March 4th? → candles table
• What evidence exists for this case? → evidence table

Without a database, your app has amnesia. Refresh the page, everything's gone.

Interfaces: What Users See

An interface is the surface users interact with. It shows data from the database and accepts input that changes the database.

Two main approaches:

Neither is "better." PHP is simpler for content-heavy sites. Next.js is better when you need complex interactivity (drag-and-drop, real-time updates, etc).

API Calls: The Math in Between

This is where "code" lives. An API call is just:

1. Receive a request (user clicked something, timer fired, webhook arrived)
2. Do some logic (validate, calculate, transform)
3. Read or write to the database
4. Return a response

User clicks "Place Order"
        │
        ▼
┌───────────────────────────────────────────────────┐
│                   API CALL                         │
│                                                    │
│  1. Validate: Is the card valid? Is item in stock?│
│  2. Calculate: Total = price × quantity + tax     │
│  3. Write DB: INSERT INTO orders (...)            │
│  4. Call Stripe: Charge the card                  │
│  5. Write DB: UPDATE orders SET status='paid'     │
│  6. Return: { success: true, orderId: 12345 }     │
│                                                    │
└───────────────────────────────────────────────────┘
        │
        ▼
Interface updates: "Order confirmed!"

The code inside that box? That's what Copilot writes. Your job is knowing what the box needs to do, not how to write it.

Putting It Together

Let's trace a real flow from your TradeCraft app:

User visits /backtest and clicks "Run Backtest"
                    │
                    ▼
            ┌───────────────┐
            │   INTERFACE   │
            │   (PHP page)  │
            └───────┬───────┘
                    │ POST /api/backtest.php
                    ▼
            ┌───────────────┐
            │   API CALL    │
            │               │
            │ • Parse strategy parameters
            │ • Query 2 years of candles from TimescaleDB
            │ • Simulate trades day by day
            │ • Calculate returns, win rate, drawdown
            │ • Return results as JSON
            │               │
            └───────┬───────┘
                    │
        ┌───────────┴───────────┐
        │                       │
        ▼                       ▼
┌───────────────┐       ┌───────────────┐
│   DATABASE    │       │   INTERFACE   │
│  TimescaleDB  │       │  Shows chart, │
│  (read only)  │       │  stats, trades│
└───────────────┘       └───────────────┘

The Mental Model

When you look at any feature request, break it down:

1. What data do I need? → Database tables
2. What does the user see? → Interface (page, component)
3. What happens when they act? → API call (the logic)

Then tell Copilot what to build. The architecture is yours. The syntax is mine.