01. The Problem
A personal portfolio has to solve two separate engineering problems: presenting technical work clearly and maintaining the content behind it. Hard-coded project pages make updates repetitive and couple content management too tightly to the frontend.
At the same time, a GitHub repository alone rarely provides enough context for a technical reviewer to quickly understand the architecture, engineering decisions, security controls, testing strategy, and implementation details of a project.
02. Goals
- Separate content from presentation: project and experience data should be managed independently from the frontend.
- Provide technical depth: projects should expose architecture, implementation decisions, and engineering evidence.
- Automate documentation: generating project documentation should rely on repository evidence rather than manually recreating technical context.
- Keep the platform production-oriented: authentication, validation, testing, CI, deployment, and observability should be treated as first-class concerns.
03. Solution Overview
CodeForge uses a split frontend/backend architecture. The Astro frontend is responsible for presentation and routing, while a Fastify API manages portfolio data, authentication, business logic, persistence, and AI-assisted documentation.
04. Architecture
The backend follows a Controller → Service → Repositoryarchitecture to keep HTTP concerns, business logic, and persistence responsibilities separate. Fastify application configuration is also isolated from server bootstrap, which allows the configured application to be imported directly by the test suite without starting a network listener.
Browser
│
▼
Astro + React Frontend
│
▼
Fastify API
│
├── Authentication / Validation
│
▼
Controllers
│
▼
Services
│
▼
Repositories
│
▼
MongoDB / Mongoose
AI Documentation
│
├── Public GitHub Repository Context
├── OpenAI / Gemini
▼
Persisted Markdown
│
▼
Project Case Study05. Key Design Decisions
Frontend: Astro + React
Decision: Use Astro for the application shell and content-heavy routes while retaining React integration where interactive UI behaviour is useful.
Reasoning: The portfolio is primarily content-oriented, so the architecture prioritizes lightweight rendering while keeping component-level interactivity available when needed.
Backend: Controller → Service → Repository
Decision: Keep transport handling, application logic, and persistence in separate layers.
Reasoning: This makes the backend easier to test, reason about, and extend without coupling HTTP handlers directly to MongoDB operations.
Security: Protected Administrative API
Decision: Administrative mutations require JWT authentication stored in an HTTP-only cookie.
Implementation: Helmet-based protections, restricted CORS, CSP/HSTS configuration, bcrypt password hashing, request rate limiting, schema validation, and production-safe error responses.
AI Documentation: Evidence over Generation
Decision: Generate documentation from public GitHub repository context rather than relying on unconstrained model output.
Implementation: CodeForge collects repository metadata, README content, and available project metadata, then supplies that context to an OpenAI or Gemini provider. Generated Markdown is normalized, bounded, persisted, and rendered by the portfolio.
06. Implementation Highlights
The implementation focuses on maintainability and explicit engineering boundaries rather than treating the portfolio as a purely visual frontend.
- Fastify API: typed REST endpoints with explicit request schemas and centralized error handling.
- Persistence: MongoDB with Mongoose models and repository-level data access.
- Authentication: JWT-based administrative authentication using HTTP-only cookies and secure production settings.
- AI workflow: asynchronous repository-aware documentation generation with persisted Markdown output.
- Observability: structured Fastify logging and in-process request metrics for runtime visibility.
- Deployment: Docker and Docker Compose definitions for reproducible multi-service environments.
07. Testing & Engineering Quality
Instead of presenting unverified performance or coverage numbers, the project documents the concrete verification mechanisms currently implemented in the repository.
Backend verification combines unit-level tests with HTTP integration testing, while the CI workflow provides automated checks for the repository before changes are considered complete.
08. Security Model
JWT authentication, HTTP-only cookies, secure production configuration, and bcrypt password hashing.
Helmet, CSP, HSTS, restricted CORS, frame protection, referrer policy, and cross-origin resource policy configuration.
Global request rate limiting together with stricter rate limiting around authentication.
Fastify JSON schema validation with explicit request boundaries and production-safe error responses.
09. Results
The final result is a portfolio platform that demonstrates full-stack engineering through the system itself rather than relying only on project screenshots.
More importantly, CodeForge became an engineering evidence platform: portfolio content is stored as application data, the administrative workflow is protected, the backend is testable, the system is containerized, CI validates changes, and technical documentation can be generated from repository evidence.
10. What I Learned
- Architecture matters at project scale: separating transport, business logic, and persistence makes the system substantially easier to evolve.
- Security must be designed into the application: authentication, validation, rate limiting, cookie policy, and HTTP protections cannot be treated as final-stage additions.
- AI output needs evidence: repository-grounded generation is more useful for technical documentation than unconstrained generation because it reduces unsupported claims.
- Engineering quality is broader than features: testing, CI, deployment, observability, and operational boundaries are part of the product.
11. Future Improvements
The project is intentionally extensible. Potential future work includes deeper automated repository analysis, richer documentation generation, stronger observability, expanded frontend testing, and additional deployment automation.