Designing Architecture with Copilot
Good architecture is the foundation of a sustainable project. In this phase, we'll use Copilot to design both backend and frontend, defining how they communicate through a clear API contract. Architecture isn't just "where to put files", but a set of decisions that influence scalability, testability, and maintainability of the project.
Fundamental Architectural Principles
- Separation of Concerns: Each component has a single responsibility
- Loose Coupling: Modules depend on abstractions, not implementations
- High Cohesion: Related code stays together
- Testability: Each part can be tested in isolation
- Maintainability: Code is understandable and modifiable
Series Overview
This is the third article of the series "GitHub Copilot: AI-Driven Personal Project".
| # | Module | Status |
|---|---|---|
| 1 | Foundation - Copilot as Partner | Completed |
| 2 | Ideation and Requirements | Completed |
| 3 | Backend and Frontend Architecture | You are here |
| 4 | Code Structure | Next |
| 5 | Prompt Engineering and MCP Agents | |
| 6 | Testing and Quality | |
| 7 | Documentation | |
| 8 | Deploy and DevOps | |
| 9 | Evolution and Maintenance |
Choosing Backend Architecture
For personal projects, there are different architectural patterns. The choice depends on domain complexity and team skills (you!).
Architectural Pattern Comparison
| Pattern | Complexity | When to Use | Pros | Cons |
|---|---|---|---|---|
| Simple MVC | Low | CRUD apps, prototypes | Fast to implement | Doesn't scale well |
| Layered/N-Tier | Medium | Standard business apps | Clear separation | Can become rigid |
| Clean Architecture | High | Complex domains | Maximum testability | Overengineering for MVP |
| Hexagonal | High | Many external integrations | Ports & Adapters | High boilerplate |
Advice for Personal Projects
For an MVP, use a Simplified Layered Architecture: enough structure to be maintainable, but not so complex it slows you down. You can always refactor toward Clean Architecture when the project grows.
Backend: Layered Architecture
Prompt - Backend Architecture Design
Design a backend architecture for my project.
PROJECT: TaskFlow (time tracking + task management)
STACK: Node.js + Express + TypeScript + PostgreSQL
TEAM SIZE: Solo developer
EXPECTED SCALE: 1000 users, 100k requests/day
Requirements:
- Clean separation between layers
- Easy to test each layer independently
- Scalable for future features
- Simple enough for a solo developer to maintain
- Support for both REST API and future GraphQL
Include:
1. Layer diagram with responsibilities
2. Complete folder structure with explanations
3. Data flow example for a typical request
4. Error handling strategy across layers
5. Dependency injection approachLayer Diagram
Backend - Layer Architecture
+-------------------------------------------------------------+
| PRESENTATION LAYER |
| +-----------+ +-----------+ +---------------------+ |
| | Controllers| |Middleware | | DTOs (Validation) | |
| +-----------+ +-----------+ +---------------------+ |
| Responsibility: HTTP handling, request/response transform |
+-------------------------------------------------------------+
| BUSINESS LAYER |
| +-----------+ +-----------+ +---------------------+ |
| | Services | | Use Cases | | Domain Logic | |
| +-----------+ +-----------+ +---------------------+ |
| Responsibility: Business rules, orchestration, validation |
+-------------------------------------------------------------+
| DATA ACCESS LAYER |
| +-----------+ +-----------+ +---------------------+ |
| |Repositories| | Entities | | Query Builders | |
| +-----------+ +-----------+ +---------------------+ |
| Responsibility: Data persistence, query optimization |
+-------------------------------------------------------------+
| INFRASTRUCTURE |
| +-----------+ +-----------+ +---------------------+ |
| | Database | |External APIs| | File System | |
| +-----------+ +-----------+ +---------------------+ |
| Responsibility: Concrete implementations, external deps |
+-------------------------------------------------------------+
DEPENDENCY DIRECTION
(Upper layers depend on lower layers)Dependency Rules
Correct
- Controller -> Service
- Service -> Repository
- Repository -> Database
- Service -> Interface (not implementation)
Wrong
- Controller -> Database (skip layer)
- Repository -> Controller (reverse direction)
- Service -> Express Request (coupling to framework)
- Business logic in Controller
Request Flow
Let's see how a request traverses all layers, from HTTP to persistence.
TypeScript - Complete Request Flow
// =============================================================
// 1. ROUTE DEFINITION (Presentation Layer)
// =============================================================
// routes/task.routes.ts
import {{ '{' }} Router {{ '}' }} from 'express';
import {{ '{' }} TaskController {{ '}' }} from '../controllers/task.controller';
import {{ '{' }} authMiddleware {{ '}' }} from '../middleware/auth.middleware';
import {{ '{' }} validateDto {{ '}' }} from '../middleware/validation.middleware';
import {{ '{' }} CreateTaskDto {{ '}' }} from '../dto/create-task.dto';
const router = Router();
const controller = new TaskController();
router.post(
'/',
authMiddleware, // Verify JWT
validateDto(CreateTaskDto), // Validate body
controller.create.bind(controller) // Handle request
);
export default router;
// =============================================================
// 2. DTO WITH VALIDATION (Presentation Layer)
// =============================================================
// dto/create-task.dto.ts
import {{ '{' }} IsString, IsOptional, IsDateString, MinLength, MaxLength {{ '}' }} from 'class-validator';
export class CreateTaskDto {{ '{' }}
@IsString()
@MinLength(3, {{ '{' }} message: 'Title must be at least 3 characters' {{ '}' }})
@MaxLength(100)
title: string;
@IsOptional()
@IsString()
@MaxLength(1000)
description?: string;
@IsOptional()
@IsDateString()
dueDate?: string;
{{ '}' }}
// =============================================================
// 3. CONTROLLER (Presentation Layer)
// =============================================================
// controllers/task.controller.ts
import {{ '{' }} Request, Response, NextFunction {{ '}' }} from 'express';
import {{ '{' }} TaskService {{ '}' }} from '../services/task.service';
import {{ '{' }} CreateTaskDto {{ '}' }} from '../dto/create-task.dto';
export class TaskController {{ '{' }}
private taskService: TaskService;
constructor() {{ '{' }}
this.taskService = new TaskService();
{{ '}' }}
async create(req: Request, res: Response, next: NextFunction) {{ '{' }}
try {{ '{' }}
const userId = req.user.id; // From auth middleware
const dto: CreateTaskDto = req.body;
const task = await this.taskService.createTask(userId, dto);
res.status(201).json({{ '{' }}
success: true,
data: task
{{ '}' }});
{{ '}' }} catch (error) {{ '{' }}
next(error); // Forward to error middleware
{{ '}' }}
{{ '}' }}
{{ '}' }}
// =============================================================
// 4. SERVICE (Business Layer)
// =============================================================
// services/task.service.ts
import {{ '{' }} TaskRepository {{ '}' }} from '../repositories/task.repository';
import {{ '{' }} Task {{ '}' }} from '../entities/task.entity';
import {{ '{' }} CreateTaskDto {{ '}' }} from '../dto/create-task.dto';
import {{ '{' }} ValidationError {{ '}' }} from '../errors/validation.error';
export class TaskService {{ '{' }}
private taskRepo: TaskRepository;
constructor() {{ '{' }}
this.taskRepo = new TaskRepository();
{{ '}' }}
async createTask(userId: string, dto: CreateTaskDto): Promise<Task> {{ '{' }}
// Business rule: due date must be in future
if (dto.dueDate && new Date(dto.dueDate) < new Date()) {{ '{' }}
throw new ValidationError('Due date must be in the future');
{{ '}' }}
// Business rule: max 100 active tasks per user
const activeTasksCount = await this.taskRepo.countActiveByUser(userId);
if (activeTasksCount >= 100) {{ '{' }}
throw new ValidationError('Maximum 100 active tasks allowed');
{{ '}' }}
// Create entity
const task = new Task({{ '{' }}
userId,
title: dto.title,
description: dto.description,
dueDate: dto.dueDate ? new Date(dto.dueDate) : null,
status: 'TODO',
createdAt: new Date()
{{ '}' }});
// Persist and return
return this.taskRepo.save(task);
{{ '}' }}
{{ '}' }}
// =============================================================
// 5. REPOSITORY (Data Access Layer)
// =============================================================
// repositories/task.repository.ts
import {{ '{' }} db {{ '}' }} from '../database/connection';
import {{ '{' }} Task {{ '}' }} from '../entities/task.entity';
export class TaskRepository {{ '{' }}
async save(task: Task): Promise<Task> {{ '{' }}
const result = await db.query(
`INSERT INTO tasks (id, user_id, title, description, due_date, status, created_at)
VALUES ($1, $2, $3, $4, $5, $6, $7)
RETURNING *`,
[task.id, task.userId, task.title, task.description,
task.dueDate, task.status, task.createdAt]
);
return Task.fromRow(result.rows[0]);
{{ '}' }}
async countActiveByUser(userId: string): Promise<number> {{ '{' }}
const result = await db.query(
`SELECT COUNT(*) FROM tasks
WHERE user_id = $1 AND status != 'DONE' AND deleted_at IS NULL`,
[userId]
);
return parseInt(result.rows[0].count);
{{ '}' }}
{{ '}' }}Consistent Error Handling
A well-designed error handling system simplifies debugging and UX.
TypeScript - Error Handling System
// =============================================================
// errors/app-error.ts - Base Error Class
// =============================================================
export class AppError extends Error {{ '{' }}
public readonly statusCode: number;
public readonly code: string;
public readonly isOperational: boolean;
public readonly details?: unknown;
constructor(
message: string,
statusCode: number = 500,
code: string = 'INTERNAL_ERROR',
details?: unknown
) {{ '{' }}
super(message);
this.statusCode = statusCode;
this.code = code;
this.isOperational = true;
this.details = details;
Error.captureStackTrace(this, this.constructor);
{{ '}' }}
{{ '}' }}
// =============================================================
// errors/specific-errors.ts - Domain Specific Errors
// =============================================================
export class ValidationError extends AppError {{ '{' }}
constructor(message: string, details?: unknown) {{ '{' }}
super(message, 400, 'VALIDATION_ERROR', details);
{{ '}' }}
{{ '}' }}
export class NotFoundError extends AppError {{ '{' }}
constructor(resource: string, id?: string) {{ '{' }}
const message = id
? `